rerobe-js-orm 4.8.8 → 4.9.0

package/lib/helpers/PricingHelpers.d.ts

@@ -0,0 +1,29 @@
+import { IsTaxableValue, OrderLinePricing, OrderLinePricingLike, ProductPricing, ProductPricingLike, RateInput, TaxResolution, VariantPricing, VariantPricingLike } from '../types/pricing-types';
+export default class PricingHelpers {
+    static isTaxableYes(value: IsTaxableValue): boolean;
+    static resolveTaxRate(input: RateInput): TaxResolution;
+    static passThroughString(value: string | number | undefined | null): string;
+    static toNetString(gross: string | number | undefined | null, rate: number): string;
+    static toGrossString(net: string | number | undefined | null, rate: number): string;
+    static getProductPricing(product: ProductPricingLike | null | undefined, opts: {
+        countryCode: string;
+    }): ProductPricing;
+    static getVariantPricing(variant: VariantPricingLike | null | undefined, parent: ProductPricingLike | null | undefined, opts: {
+        countryCode: string;
+    }): VariantPricing;
+    static getOrderLinePricing(line: OrderLinePricingLike | null | undefined): OrderLinePricing;
+    static buildAccountingSavePatch(values: {
+        price?: number | string;
+        isTaxable?: IsTaxableValue;
+        taxCategory?: string | null;
+    }, countryCode: string): {
+        price: string;
+        taxCategory: string;
+        isTaxable: 'yes' | 'no';
+    };
+    static buildAccountingEditSeed(values: {
+        price?: number | string;
+        isTaxable?: IsTaxableValue;
+        taxCategory?: string | null;
+    }, countryCode: string): string;
+}

package/lib/helpers/PricingHelpers.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tax_constants_1 = require("../constants/tax-constants");
+const TaxHelpers_1 = require("./TaxHelpers");
+// Catalog vs frozen-rate type narrow used by `resolveTaxRate`. We treat
+// any object that surfaces `countryCode` or `taxCategory` as catalog mode
+// and everything else as frozen-rate mode (which only carries `taxRate`
+// and `isTaxable`).
+function isCatalogInput(input) {
+    return input.countryCode !== undefined || input.taxCategory !== undefined;
+}
+function coerceFrozenRate(rate) {
+    if (rate === null || rate === undefined)
+        return 0;
+    const n = typeof rate === 'number' ? rate : parseFloat(String(rate));
+    return Number.isFinite(n) && n > 0 ? n : 0;
+}
+function readMoneyAmount(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'number' || typeof value === 'string')
+        return value;
+    return value.amount === undefined ? null : value.amount;
+}
+// Pricing helpers — pure functions that resolve effective tax rates and
+// project net/gross snapshots for products, variants, and order lines.
+//
+// Two lookup modes:
+//   - Catalog (country + tax category) → product editors, list screens
+//   - Frozen rate (taxRate captured at order time) → orders, refunds, POS
+//
+// Lifted from the ribbn-web-app `lib/pricing/core` module so backend,
+// mobile, and web all share the same conversions and snapshot shapes.
+class PricingHelpers {
+    static isTaxableYes(value) {
+        if (value === true)
+            return true;
+        if (typeof value === 'string')
+            return value.toLowerCase() === 'yes';
+        return false;
+    }
+    static resolveTaxRate(input) {
+        const taxable = PricingHelpers.isTaxableYes(input.isTaxable);
+        if (!taxable) {
+            return { rate: 0, taxable: false };
+        }
+        if (isCatalogInput(input)) {
+            const category = TaxHelpers_1.default.normalizeTaxCategory(input.taxCategory);
+            if (category === tax_constants_1.TAX_CATEGORIES.EXEMPT) {
+                return { rate: 0, taxable: true, category };
+            }
+            return {
+                rate: TaxHelpers_1.default.getTaxRate(input.countryCode, category),
+                taxable: true,
+                category,
+            };
+        }
+        const frozen = input;
+        return { rate: coerceFrozenRate(frozen.taxRate), taxable: true };
+    }
+    // Pass-through string normalization used when no rate applies (exempt
+    // / non-taxable). Trims and returns the stored value as a plain string
+    // so callers don't have to special-case empty inputs.
+    static passThroughString(value) {
+        if (value === null || value === undefined)
+            return '';
+        if (typeof value === 'number')
+            return String(value);
+        return String(value).trim();
+    }
+    static toNetString(gross, rate) {
+        return TaxHelpers_1.default.grossToNetPriceString(gross, rate);
+    }
+    static toGrossString(net, rate) {
+        return TaxHelpers_1.default.netToGrossPriceString(net, rate);
+    }
+    // Pricing snapshot for a product (parent fields). Resolves the rate
+    // once, then projects every price-like field into both stored (net)
+    // and displayable (gross) forms.
+    static getProductPricing(product, opts) {
+        const safeProduct = product || {};
+        const { rate, taxable } = PricingHelpers.resolveTaxRate({
+            countryCode: opts.countryCode,
+            taxCategory: safeProduct.taxCategory,
+            isTaxable: safeProduct.isTaxable,
+        });
+        const projectGross = (net) => {
+            const trimmed = PricingHelpers.passThroughString(net);
+            if (!trimmed)
+                return '';
+            if (!rate)
+                return trimmed;
+            return PricingHelpers.toGrossString(trimmed, rate);
+        };
+        return {
+            rate,
+            taxable,
+            priceNet: PricingHelpers.passThroughString(safeProduct.price),
+            salePriceNet: PricingHelpers.passThroughString(safeProduct.salePrice),
+            compareAtPriceNet: PricingHelpers.passThroughString(safeProduct.compareAtPrice),
+            costPerItemNet: PricingHelpers.passThroughString(safeProduct.costPerItem),
+            priceGross: projectGross(safeProduct.price),
+            salePriceGross: projectGross(safeProduct.salePrice),
+            compareAtPriceGross: projectGross(safeProduct.compareAtPrice),
+            costPerItemGross: projectGross(safeProduct.costPerItem),
+        };
+    }
+    // Pricing snapshot for a single variant inventory row. Honors the
+    // variant-level `taxable` override; falls back to the parent product's
+    // `isTaxable` and `taxCategory` when the variant doesn't specify one.
+    static getVariantPricing(variant, parent, opts) {
+        const safeVariant = variant || {};
+        const safeParent = parent || {};
+        const variantTaxableSpecified = safeVariant.taxable !== undefined && safeVariant.taxable !== null;
+        const effectiveTaxable = variantTaxableSpecified
+            ? PricingHelpers.isTaxableYes(safeVariant.taxable)
+                ? 'yes'
+                : 'no'
+            : safeParent.isTaxable;
+        const { rate, taxable } = PricingHelpers.resolveTaxRate({
+            countryCode: opts.countryCode,
+            taxCategory: safeParent.taxCategory,
+            isTaxable: effectiveTaxable,
+        });
+        const projectGross = (net) => {
+            const trimmed = PricingHelpers.passThroughString(net);
+            if (!trimmed)
+                return '';
+            if (!rate)
+                return trimmed;
+            return PricingHelpers.toGrossString(trimmed, rate);
+        };
+        return {
+            rate,
+            taxable,
+            priceNet: PricingHelpers.passThroughString(safeVariant.price),
+            salePriceNet: PricingHelpers.passThroughString(safeVariant.salePrice),
+            compareAtPriceNet: PricingHelpers.passThroughString(safeVariant.compareAtPrice),
+            costPerItemNet: PricingHelpers.passThroughString(safeVariant.costPerItem),
+            priceGross: projectGross(safeVariant.price),
+            salePriceGross: projectGross(safeVariant.salePrice),
+            compareAtPriceGross: projectGross(safeVariant.compareAtPrice),
+            costPerItemGross: projectGross(safeVariant.costPerItem),
+        };
+    }
+    // Pricing snapshot for an order/refund/POS line item. Uses the line's
+    // frozen `taxRate` field captured at order creation rather than
+    // consulting the catalog — at order time we want to display the tax
+    // that was actually charged, not whatever the current catalog says.
+    static getOrderLinePricing(line) {
+        const safeLine = line || {};
+        const { rate, taxable } = PricingHelpers.resolveTaxRate({
+            taxRate: safeLine.taxRate,
+            isTaxable: safeLine.isTaxable,
+        });
+        const projectGross = (net) => {
+            const trimmed = PricingHelpers.passThroughString(net);
+            if (!trimmed)
+                return '';
+            if (!rate)
+                return trimmed;
+            return PricingHelpers.toGrossString(trimmed, rate);
+        };
+        const unit = PricingHelpers.passThroughString(readMoneyAmount(safeLine.originalUnitPrice));
+        const total = PricingHelpers.passThroughString(readMoneyAmount(safeLine.originalTotalPrice));
+        const sale = PricingHelpers.passThroughString(readMoneyAmount(safeLine.salePrice));
+        return {
+            rate,
+            taxable,
+            unitPriceNet: unit,
+            unitPriceGross: projectGross(unit),
+            totalPriceNet: total,
+            totalPriceGross: projectGross(total),
+            salePriceNet: sale,
+            salePriceGross: projectGross(sale),
+        };
+    }
+    // Convenience helper for the retail accounting "save" path:
+    // - merchant types gross
+    // - we resolve the catalog rate
+    // - return the triple to persist (net price + normalized category +
+    //   normalized isTaxable)
+    //
+    // Lifted from ribbn-web-app `ProductDetailsV2.buildAccountingSavePatch`.
+    static buildAccountingSavePatch(values, countryCode) {
+        const isTaxable = PricingHelpers.isTaxableYes(values.isTaxable);
+        const taxCategory = isTaxable ? TaxHelpers_1.default.normalizeTaxCategory(values.taxCategory) : tax_constants_1.TAX_CATEGORIES.EXEMPT;
+        const { rate } = PricingHelpers.resolveTaxRate({
+            countryCode,
+            taxCategory,
+            isTaxable: isTaxable ? 'yes' : 'no',
+        });
+        return {
+            price: PricingHelpers.toNetString(values.price, rate),
+            taxCategory: String(taxCategory),
+            isTaxable: isTaxable ? 'yes' : 'no',
+        };
+    }
+    // Convenience helper for the retail accounting "edit" path: seeds the
+    // price input with the gross-converted value of the stored net price
+    // so the merchant always sees / edits gross.
+    static buildAccountingEditSeed(values, countryCode) {
+        const taxCategory = TaxHelpers_1.default.normalizeTaxCategory(values.taxCategory);
+        const isTaxable = PricingHelpers.isTaxableYes(values.isTaxable);
+        const { rate } = PricingHelpers.resolveTaxRate({
+            countryCode,
+            taxCategory,
+            isTaxable: isTaxable ? 'yes' : 'no',
+        });
+        if (!rate)
+            return String(values.price === undefined || values.price === null ? '' : values.price);
+        return PricingHelpers.toGrossString(values.price, rate);
+    }
+}
+exports.default = PricingHelpers;

package/lib/helpers/ProductInventoryHelpers.d.ts

@@ -0,0 +1,31 @@
+export declare const PLACEHOLDER_VARIANT_ID = "default";
+export interface PlaceholderVariantLocation {
+    id: string;
+    name: string;
+    incomingAmount: number;
+    availableAmount: number;
+}
+export interface PlaceholderVariantInventory {
+    id: string;
+    options: {
+        [k: string]: never;
+    };
+    price?: string | null;
+    sku?: string | null;
+    taxable?: 'yes' | 'no' | null;
+    continueSellingWhenOutOfStock?: boolean | null;
+    locations?: PlaceholderVariantLocation[] | null;
+}
+export interface PlaceholderVariantInput {
+    sku?: string | null;
+    price?: string | null;
+    taxable?: 'yes' | 'no' | null;
+    quantity?: number;
+    locationId?: string;
+    locationName?: string;
+    continueSellingWhenOutOfStock?: boolean;
+}
+export default class ProductInventoryHelpers {
+    static buildPlaceholderVariantInventory(input?: PlaceholderVariantInput): PlaceholderVariantInventory[];
+    static aggregateQuantityFromPlaceholder(placeholder: PlaceholderVariantInventory[] | null | undefined): number;
+}

package/lib/helpers/ProductInventoryHelpers.js

@@ -0,0 +1,66 @@
+"use strict";
+// Placeholder variant inventory + aggregation helpers. Pure,
+// dependency-free — used by non-clothing retail product creation flows
+// (cafe items, services, supplies) that need a single-row
+// variantInventory entry without modeling explicit size/color axes.
+//
+// Modelling these items as MULTIVARIANT with a one-row variantInventory
+// keeps every retail SKU under existing ORM productClass values (no new
+// productClass, no SUPPLY misuse) and gives every flow that needs
+// per-location stock the same shape.
+//
+// Tracked items: pass the merchant-entered `quantity` and the
+// merchant's default location id. Indefinite-stock items (cafe /
+// services): pass quantity 0 and `continueSellingWhenOutOfStock: true`
+// — the order processor uses `product.stockStatus = IN_STOCK_UNLIMITED`
+// to skip the actual decrement (see `Product.isUntrackedStock`).
+//
+// Lifted from the ribbn-web-app `lib/utilities/placeholderVariant.ts`
+// shim so backend, mobile, and web share the same construction rule.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLACEHOLDER_VARIANT_ID = void 0;
+exports.PLACEHOLDER_VARIANT_ID = 'default';
+class ProductInventoryHelpers {
+    static buildPlaceholderVariantInventory(input = {}) {
+        const sku = input.sku === undefined || input.sku === null ? '' : input.sku;
+        const price = input.price === undefined || input.price === null ? '' : input.price;
+        const taxable = input.taxable === undefined ? null : input.taxable;
+        const quantity = input.quantity === undefined ? 0 : input.quantity;
+        const locationId = input.locationId === undefined ? '' : input.locationId;
+        const locationName = input.locationName === undefined ? '' : input.locationName;
+        const continueSellingWhenOutOfStock = input.continueSellingWhenOutOfStock === undefined ? false : input.continueSellingWhenOutOfStock;
+        const safeQuantity = Number.isFinite(quantity) ? Math.max(0, Math.floor(Number(quantity))) : 0;
+        const variant = {
+            id: exports.PLACEHOLDER_VARIANT_ID,
+            options: {},
+            price: price ? String(price) : '',
+            sku: sku ? String(sku) : '',
+            taxable: taxable || null,
+            continueSellingWhenOutOfStock: Boolean(continueSellingWhenOutOfStock),
+            locations: locationId
+                ? [
+                    {
+                        id: locationId,
+                        name: locationName || '',
+                        incomingAmount: 0,
+                        availableAmount: safeQuantity,
+                    },
+                ]
+                : [],
+        };
+        return [variant];
+    }
+    // Aggregate quantity across the placeholder variant's locations.
+    // Mirrors what `ProductFormState.aggregateInventoryLocationsFromVariants`
+    // does for the multi-axis case so the product-level `quantity` stays
+    // accurate.
+    static aggregateQuantityFromPlaceholder(placeholder) {
+        if (!Array.isArray(placeholder) || placeholder.length === 0)
+            return 0;
+        const variant = placeholder[0];
+        if (!variant || !variant.locations || variant.locations.length === 0)
+            return 0;
+        return variant.locations.reduce((acc, loc) => acc + (Number(loc.availableAmount) || 0), 0);
+    }
+}
+exports.default = ProductInventoryHelpers;

package/lib/helpers/ProductSkuHelpers.d.ts

@@ -0,0 +1,13 @@
+export declare const SKU_ALPHABET = "ABCDEFGHJKMNPQRSTVWXYZ23456789";
+export declare const DEFAULT_SKU_LENGTH = 10;
+export default class ProductSkuHelpers {
+    static generateSku(length?: number): string;
+    static effectiveVariantSku(product: {
+        sku?: string | null;
+    } | null | undefined, variant: {
+        sku?: string | null;
+    } | null | undefined): string;
+    static describeVariantOptions(options: {
+        [k: string]: string;
+    } | null | undefined): string;
+}

package/lib/helpers/ProductSkuHelpers.js

@@ -0,0 +1,70 @@
+"use strict";
+// SKU and variant-description helpers. Pure, dependency-free — used by
+// retail product creation, label printing, receipt rendering, and any
+// surface that needs to derive a scan-friendly SKU or human-readable
+// variant title from a product / variant pair.
+//
+// Lifted from the ribbn-web-app `lib/utilities/sku.ts` shim so backend,
+// mobile, and web all consume the same alphabet, fallback rules, and
+// variant-description join.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SKU_LENGTH = exports.SKU_ALPHABET = void 0;
+// 30-character Crockford-style alphabet that strips visually ambiguous
+// characters (0/O, 1/I/L, U) so a merchant who has to read or type a
+// SKU off a printed tag isn't tripped up by lookalike glyphs.
+//
+// 10 characters from a 30-character alphabet → ~49 bits of entropy.
+// Within a single merchant's catalog the collision probability is
+// effectively zero (you'd need ~10 million products before the chance
+// hits 1%).
+exports.SKU_ALPHABET = 'ABCDEFGHJKMNPQRSTVWXYZ23456789';
+exports.DEFAULT_SKU_LENGTH = 10;
+class ProductSkuHelpers {
+    // Generate a short, scan-friendly random SKU. Used as the default
+    // value when creating products in flows where the merchant hasn't
+    // provided their own SKU. The value is short enough to fit a Code 128
+    // barcode on even the smallest practical price-tag labels (≈30×20 mm).
+    static generateSku(length = exports.DEFAULT_SKU_LENGTH) {
+        const buf = new Uint8Array(length);
+        if (typeof globalThis !== 'undefined' &&
+            typeof globalThis.crypto !== 'undefined' &&
+            typeof globalThis.crypto.getRandomValues === 'function') {
+            globalThis.crypto.getRandomValues(buf);
+        }
+        else {
+            // SSR / test environments without WebCrypto. Not cryptographically
+            // strong, but acceptable for a SKU's collision-avoidance use case.
+            for (let i = 0; i < length; i = i + 1) {
+                buf[i] = Math.floor(Math.random() * 256);
+            }
+        }
+        let out = '';
+        for (let i = 0; i < length; i = i + 1) {
+            out = out + exports.SKU_ALPHABET[buf[i] % exports.SKU_ALPHABET.length];
+        }
+        return out;
+    }
+    // Resolves the SKU that should be encoded on a printed label / scanned
+    // barcode for a specific variant. Falls back to the parent product's
+    // SKU when the variant doesn't carry its own, matching the convention
+    // the retail entry surfaces in the variants table ("Leave a row's SKU
+    // blank to fall back to the product SKU").
+    static effectiveVariantSku(product, variant) {
+        const variantSku = String((variant && variant.sku) || '').trim();
+        if (variantSku)
+            return variantSku;
+        return String((product && product.sku) || '').trim();
+    }
+    // Builds a human-readable variant title from a variantInventory row's
+    // `options` map (e.g. `{ Size: 'M', Color: 'Black' }` → "M / Black").
+    // Useful both on printed labels and inside cart line item summaries.
+    static describeVariantOptions(options) {
+        if (!options)
+            return '';
+        return Object.keys(options)
+            .map((k) => String(options[k] || '').trim())
+            .filter(Boolean)
+            .join(' / ');
+    }
+}
+exports.default = ProductSkuHelpers;

package/lib/helpers/TaxHelpers.d.ts

@@ -0,0 +1,15 @@
+import { TaxCategoryValue } from '../constants/tax-constants';
+import { TaxCategoryOption } from '../types/pricing-types';
+export default class TaxHelpers {
+    static normalizeTaxCategory(taxCategory?: string | null): TaxCategoryValue;
+    static getTaxCategoryLabel(taxCategory?: string | null): string;
+    static normalizeCountryCode(countryCode?: string | null): string;
+    static getCountryTaxRates(countryCode?: string | null): {
+        [category: string]: number;
+    };
+    static getTaxRate(countryCode?: string | null, taxCategory?: string | null): number;
+    static formatRatePercent(rate: number): string;
+    static getTaxCategoryOptionsWithRates(countryCode?: string | null): TaxCategoryOption[];
+    static grossToNetPriceString(grossPrice: string | number | undefined | null, rate: number): string;
+    static netToGrossPriceString(netPrice: string | number | undefined | null, rate: number): string;
+}

package/lib/helpers/TaxHelpers.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tax_constants_1 = require("../constants/tax-constants");
+// Tax-rate and category helpers. Pure, dependency-free — safe to use in
+// backend services, mobile, and web. Lifted from the ribbn-web-app
+// `lib/utilities/tax.ts` shim so every surface that needs to read or
+// edit a product's tax shape consumes the same normalization.
+class TaxHelpers {
+    static normalizeTaxCategory(taxCategory) {
+        const raw = String(taxCategory || tax_constants_1.TAX_CATEGORIES.STANDARD).trim();
+        return tax_constants_1.TAX_CATEGORY_ALIASES[raw] || tax_constants_1.TAX_CATEGORY_ALIASES[raw.toUpperCase()] || tax_constants_1.TAX_CATEGORIES.STANDARD;
+    }
+    static getTaxCategoryLabel(taxCategory) {
+        return tax_constants_1.TAX_CATEGORY_BASE_LABELS[TaxHelpers.normalizeTaxCategory(taxCategory)];
+    }
+    static normalizeCountryCode(countryCode) {
+        const cc = String(countryCode || '').toUpperCase();
+        return tax_constants_1.TAX_CATEGORY_RATES[cc] ? cc : tax_constants_1.FALLBACK_TAX_COUNTRY_CODE;
+    }
+    static getCountryTaxRates(countryCode) {
+        return tax_constants_1.TAX_CATEGORY_RATES[TaxHelpers.normalizeCountryCode(countryCode)];
+    }
+    static getTaxRate(countryCode, taxCategory) {
+        const rates = TaxHelpers.getCountryTaxRates(countryCode);
+        const cat = TaxHelpers.normalizeTaxCategory(taxCategory);
+        if (cat in rates)
+            return rates[cat];
+        return rates.STANDARD || 0;
+    }
+    // Format a rate as a short percent label, e.g. 0.25 -> "25%", 0.055 -> "5.5%".
+    static formatRatePercent(rate) {
+        if (!rate)
+            return '0%';
+        const pct = rate * 100;
+        if (Math.abs(pct - Math.round(pct)) < 0.05) {
+            return `${Math.round(pct)}%`;
+        }
+        return `${Number(pct.toFixed(2))}%`;
+    }
+    // Returns option list with rate-aware labels (e.g. "Standard (25%)") for the
+    // given country. Useful for select dropdowns in admin product editors.
+    static getTaxCategoryOptionsWithRates(countryCode) {
+        const rates = TaxHelpers.getCountryTaxRates(countryCode);
+        return Object.keys(tax_constants_1.TAX_CATEGORIES).map((key) => {
+            const value = tax_constants_1.TAX_CATEGORIES[key];
+            const rate = rates[value] || 0;
+            const rateLabel = TaxHelpers.formatRatePercent(rate);
+            const baseLabel = tax_constants_1.TAX_CATEGORY_BASE_LABELS[value];
+            const label = value === tax_constants_1.TAX_CATEGORIES.EXEMPT ? `${baseLabel} (no tax)` : `${baseLabel} (${rateLabel})`;
+            return { value, label, rate, rateLabel };
+        });
+    }
+    // Convert a tax-inclusive (gross) price string to a tax-exclusive (net)
+    // price string formatted with 2 decimals. Returns the original string if
+    // it can't be parsed or if rate is 0.
+    static grossToNetPriceString(grossPrice, rate) {
+        const gross = typeof grossPrice === 'number' ? grossPrice : parseFloat(String(grossPrice == null ? '' : grossPrice));
+        if (!Number.isFinite(gross) || gross <= 0) {
+            return String(grossPrice == null ? '' : grossPrice);
+        }
+        if (!rate)
+            return gross.toFixed(2);
+        return (gross / (1 + rate)).toFixed(2);
+    }
+    // Convert a stored net price back to a gross price for display in inputs.
+    static netToGrossPriceString(netPrice, rate) {
+        const net = typeof netPrice === 'number' ? netPrice : parseFloat(String(netPrice == null ? '' : netPrice));
+        if (!Number.isFinite(net) || net <= 0) {
+            return String(netPrice == null ? '' : netPrice);
+        }
+        if (!rate)
+            return net.toFixed(2);
+        return (net * (1 + rate)).toFixed(2);
+    }
+}
+exports.default = TaxHelpers;

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

@@ -0,0 +1,20 @@
+export type CommissionPolicyContext = {
+    taxableAmount: number;
+    originalRate: number;
+    marketplaceRate: number;
+};
+export type CommissionPolicyResult = {
+    originalProductCommissionAmount: number;
+    marketplaceCommissionAmount: number;
+    managedMerchantProceedsAmount: number;
+    sellerProceedsAmount: number;
+};
+export type CommissionPolicyFeeContext = {
+    stripeFee: number;
+    ribbnFee: number;
+};
+export interface CommissionPolicy {
+    readonly basis: string;
+    calculate(context: CommissionPolicyContext, feeContext: CommissionPolicyFeeContext): CommissionPolicyResult;
+}
+export declare const roundCommissionAmount: (value: number) => number;

package/lib/helpers/marketplace/CommissionPolicy.js

@@ -0,0 +1,9 @@
+"use strict";
+// Strategy interface for marketplace commission calculation. 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 code paths.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.roundCommissionAmount = void 0;
+const roundCommissionAmount = (value) => Number(Number(value || 0).toFixed(2));
+exports.roundCommissionAmount = roundCommissionAmount;

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

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

package/lib/helpers/marketplace/CommissionPolicyRegistry.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.has = exports.get = exports.register = void 0;
+const marketplace_constants_1 = require("../../constants/marketplace-constants");
+const LineNetCommissionPolicy_1 = require("./LineNetCommissionPolicy");
+const OriginalCommissionShareCommissionPolicy_1 = require("./OriginalCommissionShareCommissionPolicy");
+// Process-wide registry for marketplace commission policies. Built-in
+// strategies are registered eagerly so the default exported registry is
+// usable without setup. New bases can be added at runtime via
+// `register(policy)` to satisfy the open/closed principle.
+const REGISTRY = {};
+const register = (policy) => {
+    REGISTRY[policy.basis] = policy;
+};
+exports.register = register;
+const get = (basis) => REGISTRY[basis] || REGISTRY[marketplace_constants_1.DEFAULT_MARKETPLACE_COMMISSION_BASIS];
+exports.get = get;
+const has = (basis) => Boolean(REGISTRY[basis]);
+exports.has = has;
+(0, exports.register)(new LineNetCommissionPolicy_1.default());
+(0, exports.register)(new OriginalCommissionShareCommissionPolicy_1.default());

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

@@ -0,0 +1,5 @@
+import { FeeAllocationContext, FeeAllocationPolicy } from './FeeAllocationPolicy';
+export default class EvenPerSellerStripeFeePolicy implements FeeAllocationPolicy {
+    readonly basis: "EVEN_PER_SELLER";
+    allocate({ totalFeeAmount, basket }: FeeAllocationContext): MarketplaceFeeAllocation[];
+}

package/lib/helpers/marketplace/EvenPerSellerStripeFeePolicy.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const marketplace_constants_1 = require("../../constants/marketplace-constants");
+const FeeAllocationPolicy_1 = require("./FeeAllocationPolicy");
+// Mirrors the existing backend `applyStripeFeeRecoupBump` semantics:
+//   merchantShare    = totalFee / numUniqueManagedSellersInBasket
+//   linePerSellerCt  = lines for that seller
+//   per-line amount  = merchantShare / linePerSellerCt
+//
+// Lines whose `lineNetAmount` is non-positive are skipped so we never spread
+// a fee onto a freebie line, matching the legacy guard against zero-priced
+// items.
+class EvenPerSellerStripeFeePolicy {
+    constructor() {
+        this.basis = marketplace_constants_1.MARKETPLACE_FEE_ALLOCATION_BASES.evenPerSeller;
+    }
+    allocate({ totalFeeAmount, basket }) {
+        if (!Array.isArray(basket) || basket.length === 0) {
+            return [];
+        }
+        const safeTotal = Number(totalFeeAmount);
+        if (!Number.isFinite(safeTotal) || safeTotal <= 0) {
+            return basket.map((line) => ({ lineKey: line.lineKey, amount: 0 }));
+        }
+        const eligibleLines = basket.filter((line) => Number.isFinite(Number(line === null || line === void 0 ? void 0 : line.lineNetAmount)) &&
+            Number(line.lineNetAmount) > 0 &&
+            Boolean(line.sellerMerchantId));
+        if (eligibleLines.length === 0) {
+            return basket.map((line) => ({ lineKey: line.lineKey, amount: 0 }));
+        }
+        const sellerIds = Array.from(new Set(eligibleLines.map((line) => String(line.sellerMerchantId))));
+        const merchantShare = safeTotal / sellerIds.length;
+        const lineCountByVendor = sellerIds.reduce((acc, sellerId) => {
+            acc[sellerId] = eligibleLines.filter((line) => line.sellerMerchantId === sellerId).length;
+            return acc;
+        }, {});
+        const allocations = basket.map((line) => {
+            const vendorLineCount = lineCountByVendor[String(line.sellerMerchantId)] || 0;
+            const isEligible = vendorLineCount > 0 && Number.isFinite(Number(line === null || line === void 0 ? void 0 : line.lineNetAmount)) && Number(line.lineNetAmount) > 0;
+            const amount = isEligible ? (0, FeeAllocationPolicy_1.roundFeeAmount)(merchantShare / vendorLineCount) : 0;
+            return { lineKey: line.lineKey, amount };
+        });
+        return (0, FeeAllocationPolicy_1.reconcileAllocationsToTotal)(allocations, safeTotal);
+    }
+}
+exports.default = EvenPerSellerStripeFeePolicy;

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

@@ -0,0 +1,10 @@
+export type FeeAllocationContext = {
+    totalFeeAmount: number;
+    basket: MarketplaceFeeBasketLine[];
+};
+export interface FeeAllocationPolicy {
+    readonly basis: string;
+    allocate(context: FeeAllocationContext): MarketplaceFeeAllocation[];
+}
+export declare const roundFeeAmount: (value: number) => number;
+export declare const reconcileAllocationsToTotal: (allocations: MarketplaceFeeAllocation[], totalFeeAmount: number) => MarketplaceFeeAllocation[];