@aptos-scp/scp-component-store-selling-features-domain-model 2.28.0 → 2.29.0

package/lib/domain/UIBusinessEventTypes.d.ts

@@ -151,6 +151,7 @@ export declare const CUSTOMER_INPUT_EVENT: string;
 export declare const CUSTOMER_INPUT_RESULT_EVENT: string;
 export declare const PAYMENT_ACCOUNT_HOLDER_VALIDATE_EVENT: string;
 export declare const SHIPPING_FEE_REFUND_EVENT: string;
+export declare const RETURN_ORDER_SHIPPING_FEE_REFUND_EVENT: string;
 export declare const RETURN_ITEM_EVENT: string;
 export declare const ITEM_FEE_REFUND_EVENT: string;
 export declare const ORDER_ITEM_EVENT: string;
@@ -274,6 +275,7 @@ export declare const EXIT_RETURN_WITH_TRANSACTION_EVENT: string;
 export declare const RECORD_TRANSACTION_FOR_RETURN_EVENT: string;
 export declare const RECORD_RELATED_TRANSACTIONS_FOR_RETURN_EVENT: string;
 export declare const RECORD_RELATED_TRANSACTION_FOR_RETURN_EVENT: string;
+export declare const RECORD_RELATED_ORDER_FOR_RETURN_EVENT: string;
 export declare const SELECT_TRANSACTION_FOR_RETURN_EVENT: string;
 export declare const RECORD_TRANSACTION_FOR_ORDER_EVENT: string;
 export declare const START_TILL_RECONCILIATION_EVENT = "StartTillReconciliation";

package/lib/domain/UIBusinessEventTypes.js

@@ -154,6 +154,7 @@ exports.CUSTOMER_INPUT_EVENT = "CustomerInput";
 exports.CUSTOMER_INPUT_RESULT_EVENT = "CustomerInputResult";
 exports.PAYMENT_ACCOUNT_HOLDER_VALIDATE_EVENT = "PaymentAccountHolderValidate";
 exports.SHIPPING_FEE_REFUND_EVENT = "ShippingFeeRefund";
+exports.RETURN_ORDER_SHIPPING_FEE_REFUND_EVENT = "ReturnOrderShippingFeeRefund";
 exports.RETURN_ITEM_EVENT = "ReturnItem";
 exports.ITEM_FEE_REFUND_EVENT = "RefundItemFee";
 exports.ORDER_ITEM_EVENT = "OrderItem";
@@ -281,6 +282,7 @@ exports.EXIT_RETURN_WITH_TRANSACTION_EVENT = "ExitReturnWithTransaction";
 exports.RECORD_TRANSACTION_FOR_RETURN_EVENT = "RecordTransactionForReturn";
 exports.RECORD_RELATED_TRANSACTIONS_FOR_RETURN_EVENT = "RecordRelatedTransactionsForReturn";
 exports.RECORD_RELATED_TRANSACTION_FOR_RETURN_EVENT = "RecordRelatedTransactionForReturn";
+exports.RECORD_RELATED_ORDER_FOR_RETURN_EVENT = "RecordRelatedOrderForReturn";
 exports.SELECT_TRANSACTION_FOR_RETURN_EVENT = "SelectTransactionForReturn";
 exports.RECORD_TRANSACTION_FOR_ORDER_EVENT = "RecordTransactionForOrder";
 exports.START_TILL_RECONCILIATION_EVENT = "StartTillReconciliation";

package/lib/domain/model/Constants.d.ts

@@ -461,7 +461,12 @@ export declare enum UiInputKey {
     CUSTOMER_INPUT_MODE = "input_customerInputMode",
     FORCE_FISCAL_COMPLETION = "input_forceFiscalCompletion",
     IS_FISCALISE_VOID = "input_isFiscaliseVoid",
-    PAYMENT_FUNCTION = "input_paymentFunction"
+    PAYMENT_FUNCTION = "input_paymentFunction",
+    SELECTED_RETURN_FEES = "input_selectedReturnFees",
+    SELECTED_RETURN_ITEMS = "input_selectedReturnItems",
+    FEE_LINE_FOR_REFUND = "input_feeLineForRefund",
+    FEE_REFUND_SOURCE = "input_feeRefundSource",
+    FEE_REFUNDABLE_AMOUNT = "input_feeRefundableAmount"
 }
 export declare enum CollectedDataKey {
     Abort = "abort",
@@ -649,12 +654,15 @@ export declare enum CollectedDataKey {
     OfflineAuthorizationCode = "OfflineAuthorizationCode",
     OriginalExtendedAmount = "OriginalExtendedAmount",
     Order = "order",
+    CustomerOrders = "CustomerOrders",
     OrderInquiryCustomerOrders = "orderInquiryCustomerOrders",
     LineNumberFromOrder = "lineNumberFromOrder",
     OrderLineReference = "orderLineReference",
     OrderReference = "orderReference",
     OrderReferenceId = "orderReferenceId",
     OrderReferenceOrder = "orderReferenceOrder",
+    OrderForReturn = "orderForReturn",
+    UsingExistingOrderInformation = "usingExistingOrderInformation",
     OriginalOrderTransactionReference = "originalOrderTransactionReference",
     ExtendedAmountFromExternalItem = "extendedAmountFromExternalItem",
     ExtendedAmountIncludingTaxFromExternalItem = "extendedAmountIncludingTaxFromExternalItem",

package/lib/domain/model/Constants.js

@@ -463,6 +463,11 @@ var UiInputKey;
     UiInputKey["FORCE_FISCAL_COMPLETION"] = "input_forceFiscalCompletion";
     UiInputKey["IS_FISCALISE_VOID"] = "input_isFiscaliseVoid";
     UiInputKey["PAYMENT_FUNCTION"] = "input_paymentFunction";
+    UiInputKey["SELECTED_RETURN_FEES"] = "input_selectedReturnFees";
+    UiInputKey["SELECTED_RETURN_ITEMS"] = "input_selectedReturnItems";
+    UiInputKey["FEE_LINE_FOR_REFUND"] = "input_feeLineForRefund";
+    UiInputKey["FEE_REFUND_SOURCE"] = "input_feeRefundSource";
+    UiInputKey["FEE_REFUNDABLE_AMOUNT"] = "input_feeRefundableAmount";
 })(UiInputKey = exports.UiInputKey || (exports.UiInputKey = {}));
 //
 // Keys for use in relaying data collectedData (qualification) and nonContextualData (action).
@@ -656,12 +661,15 @@ var CollectedDataKey;
     CollectedDataKey["OfflineAuthorizationCode"] = "OfflineAuthorizationCode";
     CollectedDataKey["OriginalExtendedAmount"] = "OriginalExtendedAmount";
     CollectedDataKey["Order"] = "order";
+    CollectedDataKey["CustomerOrders"] = "CustomerOrders";
     CollectedDataKey["OrderInquiryCustomerOrders"] = "orderInquiryCustomerOrders";
     CollectedDataKey["LineNumberFromOrder"] = "lineNumberFromOrder";
     CollectedDataKey["OrderLineReference"] = "orderLineReference";
     CollectedDataKey["OrderReference"] = "orderReference";
     CollectedDataKey["OrderReferenceId"] = "orderReferenceId";
     CollectedDataKey["OrderReferenceOrder"] = "orderReferenceOrder";
+    CollectedDataKey["OrderForReturn"] = "orderForReturn";
+    CollectedDataKey["UsingExistingOrderInformation"] = "usingExistingOrderInformation";
     CollectedDataKey["OriginalOrderTransactionReference"] = "originalOrderTransactionReference";
     CollectedDataKey["ExtendedAmountFromExternalItem"] = "extendedAmountFromExternalItem";
     CollectedDataKey["ExtendedAmountIncludingTaxFromExternalItem"] = "extendedAmountIncludingTaxFromExternalItem";

package/lib/domain/model/OrderHandlingSession.d.ts

@@ -0,0 +1,113 @@
+import { Money } from "@aptos-scp/scp-component-business-core";
+import { IConfigurationManager, IState } from "@aptos-scp/scp-component-store-selling-core";
+import { FeeType, IFeeLine } from "@aptos-scp/scp-types-commerce-transaction";
+import { CustomerOrder } from "@aptos-scp/scp-types-orders";
+import { IOriginalTender } from "./TenderHandlingSession";
+export declare const ORDER_HANDLING_SESSION: string;
+/**
+ * Wrapper containing original CustomerOrder plus converted/processed data for return operations.
+ * Follows the pattern from ItemHandlingSession (TransactionInformation) and TenderHandlingSession (IOriginalTransactionDetails).
+ */
+export interface OrderInformation {
+    /** The unique order reference identifier */
+    orderReferenceId: string;
+    /** The original customer order from OMS */
+    customerOrder: CustomerOrder;
+    /** Fee lines converted from order fees, ready for return operations */
+    originalFees?: IOriginalFee[];
+    /** Original tenders from the order (for future tender return logic) */
+    originalTenders?: IOriginalTender[];
+    /** Timestamp of the order information creation, for tracking order staleness*/
+    informationTimestamp: Date;
+}
+export interface IOriginalFee {
+    originalFeeAmount: Money;
+    refundedAmount: Money;
+    previouslyRefundedAmount: Money;
+    refundableAmount: Money;
+    refundAllowed: boolean;
+    feeId: string;
+    feeType: FeeType;
+    customFeeType?: string;
+    description: string;
+    longDescription: string;
+    feeLine: IFeeLine;
+}
+export declare class OrderHandlingSession implements IState {
+    private _state;
+    private _orderInformationCollection;
+    private _orderInformationForReturn?;
+    private _type;
+    static create(): OrderHandlingSession;
+    static createFromJsonObject(orderHandlingSessionJsonObject: any): OrderHandlingSession;
+    get stateValues(): Readonly<Map<string, any>>;
+    get type(): Readonly<string>;
+    get inProgress(): boolean;
+    /**
+     * Gets the collection of OrderInformation objects.
+     * This provides access to all the orders and their information.
+     */
+    get orderInformationCollection(): OrderInformation[];
+    /**
+     * Gets the OrderInformation wrapper for the order for return.
+     * This provides access to both the original order and all converted data.
+     */
+    get orderInformationForReturn(): OrderInformation | undefined;
+    /**
+     * Gets the original fee lines converted from the order for return.
+     * These are IFeeLine objects ready to be used in return operations.
+     */
+    get originalFeesForReturn(): IOriginalFee[] | undefined;
+    /**
+     * Sets an order as the order for return AND processes its information.
+     * This is the key method that converts order data for return operations.
+     *
+     * @param order The CustomerOrder to set as the order for return
+     * @param inputSource Optional source identifier
+     * @param configurationManager Configuration manager for fee definitions (optional)
+     */
+    setOrderInformationForReturn(order: CustomerOrder, configurationManager?: IConfigurationManager): OrderHandlingSession;
+    /**
+     * Selects an order from the collection to be the order for return.
+     * @param orderReferenceId The order request ID to select
+     * @param configurationManager Configuration manager for fee definitions (optional)
+     */
+    selectOrderForReturn(orderReferenceId: string): OrderHandlingSession;
+    /**
+     * Resets the session to initial state with no order information.
+     */
+    reset(): OrderHandlingSession;
+    /**
+     * Starts the order handling session (transitions to InProgress state).
+     */
+    startSession(): OrderHandlingSession;
+    /**
+     * Completes the order handling session (transitions to Completed state).
+     */
+    completeSession(): OrderHandlingSession;
+    /**
+     * Updates the refundedAmount for an IOriginalFee in the orderInformationForReturn.
+     * This is called when a shipping fee refund line is added to the transaction.
+     *
+     * @param orderReferenceId The order reference ID to identify which order's fee to update
+     * @param feeId The fee ID to identify which fee to update
+     * @param feeType The fee type to identify which fee to update
+     * @param refundAmount The amount to add to the refundedAmount (positive for refund, negative for void)
+     * @returns A new OrderHandlingSession with the updated originalFee
+     */
+    updateOriginalFeeRefundedAmount(orderReferenceId: string, feeId: string, feeType: FeeType, refundAmount: Money): OrderHandlingSession;
+    private constructor();
+    /**
+     * Processes an order for return operations by converting fees to IFeeLine.
+     * @private
+     */
+    private processOrderForReturn;
+    /**
+     * Converts order fees to IOriginalFee array for tracking refundable amounts.
+     *
+     * @private
+     */
+    private processOriginalFees;
+    private createOriginalFeeFromOrderFee;
+    private isFeeRefundAllowed;
+}

package/lib/domain/model/OrderHandlingSession.js

@@ -0,0 +1,316 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const scp_component_logging_1 = require("@aptos-scp/scp-component-logging");
+const scp_component_business_core_1 = require("@aptos-scp/scp-component-business-core");
+const scp_types_commerce_transaction_1 = require("@aptos-scp/scp-types-commerce-transaction");
+const utility_1 = require("../utility");
+const configuration_1 = require("./configuration");
+const logger = scp_component_logging_1.LogManager.getLogger("com.aptos.storesellingfeatures.domain.model.OrderHandlingSession");
+exports.ORDER_HANDLING_SESSION = "OrderHandlingSession";
+var OrderHandlingSessionState;
+(function (OrderHandlingSessionState) {
+    OrderHandlingSessionState["Initial"] = "Initial";
+    OrderHandlingSessionState["InProgress"] = "InProgress";
+    OrderHandlingSessionState["Completed"] = "Completed";
+})(OrderHandlingSessionState || (OrderHandlingSessionState = {}));
+class OrderHandlingSession {
+    constructor(state, orderInformationCollection, orderInformationForReturn) {
+        this._state = state;
+        this._orderInformationCollection = orderInformationCollection;
+        this._orderInformationForReturn = orderInformationForReturn;
+        this._type = exports.ORDER_HANDLING_SESSION;
+    }
+    static create() {
+        return new OrderHandlingSession(OrderHandlingSessionState.Initial, [], undefined);
+    }
+    static createFromJsonObject(orderHandlingSessionJsonObject) {
+        const state = orderHandlingSessionJsonObject._state;
+        const orderInformationCollection = createOrderInformationCollectionFromJson(orderHandlingSessionJsonObject._orderInformationCollection);
+        const orderInformationForReturn = createOrderInformationFromJson(orderHandlingSessionJsonObject._orderInformationForReturn);
+        return new OrderHandlingSession(state, orderInformationCollection, orderInformationForReturn);
+    }
+    get stateValues() {
+        return new Map([
+            ["OrderHandlingSession.state", this._state],
+            ["OrderHandlingSession.orderInformationCollection", this._orderInformationCollection],
+            ["OrderHandlingSession.orderInformationForReturn", this._orderInformationForReturn],
+            ["OrderHandlingSession.inProgress", this.inProgress],
+        ]);
+    }
+    get type() {
+        return this._type;
+    }
+    get inProgress() {
+        return this._state === OrderHandlingSessionState.InProgress;
+    }
+    /**
+     * Gets the collection of OrderInformation objects.
+     * This provides access to all the orders and their information.
+     */
+    get orderInformationCollection() {
+        return this._orderInformationCollection ? this._orderInformationCollection : [];
+    }
+    /**
+     * Gets the OrderInformation wrapper for the order for return.
+     * This provides access to both the original order and all converted data.
+     */
+    get orderInformationForReturn() {
+        return this._orderInformationForReturn;
+    }
+    /**
+     * Gets the original fee lines converted from the order for return.
+     * These are IFeeLine objects ready to be used in return operations.
+     */
+    get originalFeesForReturn() {
+        var _a;
+        return (_a = this._orderInformationForReturn) === null || _a === void 0 ? void 0 : _a.originalFees;
+    }
+    /**
+     * Sets an order as the order for return AND processes its information.
+     * This is the key method that converts order data for return operations.
+     *
+     * @param order The CustomerOrder to set as the order for return
+     * @param inputSource Optional source identifier
+     * @param configurationManager Configuration manager for fee definitions (optional)
+     */
+    setOrderInformationForReturn(order, configurationManager) {
+        var _a;
+        logger.traceEntry("setOrderInformationForReturn", (_a = order) === null || _a === void 0 ? void 0 : _a.orderRequestId);
+        if (!order) {
+            logger.warn("Order not provided to setOrderInformationForReturn");
+            return this;
+        }
+        // Process the order and convert fees
+        const processedOrderInfo = this.processOrderForReturn(order, configurationManager);
+        // Also add to collection if not already there, or replace if it already exists
+        const orderInformationCollection = [...(this._orderInformationCollection || [])];
+        const existingIndex = orderInformationCollection.findIndex((info) => info.orderReferenceId === order.orderRequestId);
+        if (existingIndex >= 0) {
+            // Update existing with processed data
+            orderInformationCollection[existingIndex] = processedOrderInfo;
+        }
+        else {
+            // Add new
+            orderInformationCollection.push(processedOrderInfo);
+        }
+        logger.debug(() => `Set order ${order.orderRequestId} as orderForReturn`);
+        return new OrderHandlingSession(this._state, orderInformationCollection, processedOrderInfo);
+    }
+    /**
+     * Selects an order from the collection to be the order for return.
+     * @param orderReferenceId The order request ID to select
+     * @param configurationManager Configuration manager for fee definitions (optional)
+     */
+    selectOrderForReturn(orderReferenceId) {
+        logger.traceEntry("selectOrderForReturn", orderReferenceId);
+        const orderInformationForReturn = this._orderInformationCollection.find((info) => info.orderReferenceId === orderReferenceId);
+        if (!orderInformationForReturn) {
+            logger.warn(`Order not found in collection: ${orderReferenceId}`);
+            return this;
+        }
+        return new OrderHandlingSession(this._state, this._orderInformationCollection, orderInformationForReturn);
+    }
+    /**
+     * Resets the session to initial state with no order information.
+     */
+    reset() {
+        return new OrderHandlingSession(OrderHandlingSessionState.Initial, [], undefined);
+    }
+    /**
+     * Starts the order handling session (transitions to InProgress state).
+     */
+    startSession() {
+        return new OrderHandlingSession(OrderHandlingSessionState.InProgress, this._orderInformationCollection, this._orderInformationForReturn);
+    }
+    /**
+     * Completes the order handling session (transitions to Completed state).
+     */
+    completeSession() {
+        return new OrderHandlingSession(OrderHandlingSessionState.Completed, this._orderInformationCollection, this._orderInformationForReturn);
+    }
+    /**
+     * Updates the refundedAmount for an IOriginalFee in the orderInformationForReturn.
+     * This is called when a shipping fee refund line is added to the transaction.
+     *
+     * @param orderReferenceId The order reference ID to identify which order's fee to update
+     * @param feeId The fee ID to identify which fee to update
+     * @param feeType The fee type to identify which fee to update
+     * @param refundAmount The amount to add to the refundedAmount (positive for refund, negative for void)
+     * @returns A new OrderHandlingSession with the updated originalFee
+     */
+    updateOriginalFeeRefundedAmount(orderReferenceId, feeId, feeType, refundAmount) {
+        var _a;
+        logger.traceEntry("updateOriginalFeeRefundedAmount", orderReferenceId, feeId, feeType, refundAmount);
+        // Find the order in the collection by orderReferenceId
+        const orderInfoIndex = this._orderInformationCollection.findIndex((info) => info.orderReferenceId === orderReferenceId);
+        if (orderInfoIndex < 0) {
+            logger.warn(`Order not found in collection: ${orderReferenceId}`);
+            return this;
+        }
+        const orderInfo = this._orderInformationCollection[orderInfoIndex];
+        const originalFees = orderInfo.originalFees;
+        if (!originalFees || originalFees.length === 0) {
+            logger.warn("No original fees to update");
+            return this;
+        }
+        // Find the matching fee by feeId and feeType
+        const feeIndex = originalFees.findIndex((fee) => fee.feeId === feeId && fee.feeType === feeType);
+        if (feeIndex < 0) {
+            logger.warn(`Original fee not found: feeId=${feeId}, feeType=${feeType}`);
+            return this;
+        }
+        // Create updated fees array with the new refundedAmount
+        const updatedFees = [...originalFees];
+        const originalFee = updatedFees[feeIndex];
+        const refundedAmount = scp_component_business_core_1.Money.fromIMoney(originalFee.refundedAmount);
+        const refundableAmount = scp_component_business_core_1.Money.fromIMoney(originalFee.refundableAmount);
+        const newRefundedAmount = refundedAmount.plus(refundAmount);
+        const newRefundableAmount = refundableAmount.minus(refundAmount);
+        updatedFees[feeIndex] = Object.assign(Object.assign({}, originalFee), { refundedAmount: newRefundedAmount, refundableAmount: newRefundableAmount });
+        // Create updated orderInformation
+        const updatedOrderInfo = Object.assign(Object.assign({}, orderInfo), { originalFees: updatedFees });
+        // Update the collection
+        const updatedCollection = [...this._orderInformationCollection];
+        updatedCollection[orderInfoIndex] = updatedOrderInfo;
+        // Update _orderInformationForReturn if this is the selected order
+        let updatedOrderInfoForReturn = this._orderInformationForReturn;
+        if (((_a = this._orderInformationForReturn) === null || _a === void 0 ? void 0 : _a.orderReferenceId) === orderReferenceId) {
+            updatedOrderInfoForReturn = updatedOrderInfo;
+        }
+        logger.debug(() => `Updated refundedAmount for fee ${feeId}: ${refundedAmount.amount.toString()} -> ${newRefundedAmount.amount.toString()}`);
+        return new OrderHandlingSession(this._state, updatedCollection, updatedOrderInfoForReturn);
+    }
+    /**
+     * Processes an order for return operations by converting fees to IFeeLine.
+     * @private
+     */
+    processOrderForReturn(order, configurationManager) {
+        logger.traceEntry("processOrderForReturn", order.orderRequestId);
+        const orderInfo = {
+            orderReferenceId: order.orderRequestId,
+            customerOrder: order,
+            informationTimestamp: new Date(),
+        };
+        // Convert fees to IFeeLine for return operations
+        if (order.fees && order.fees.length > 0) {
+            orderInfo.originalFees = this.processOriginalFees(order.fees, order.orderRequestId, configurationManager);
+            logger.debug(() => `Converted ${orderInfo.originalFees.length} fees for order ${order.orderRequestId}`);
+        }
+        // TODO: Future - convert tenders to IOriginalTender
+        // if (order.orderTenders?.length > 0) {
+        //   orderInfo.originalTenders = this.convertOrderTenders(order.orderTenders);
+        // }
+        return orderInfo;
+    }
+    /**
+     * Converts order fees to IOriginalFee array for tracking refundable amounts.
+     *
+     * @private
+     */
+    processOriginalFees(orderFees, orderReferenceId, configurationManager) {
+        if (!orderFees || orderFees.length === 0) {
+            return [];
+        }
+        const convertedFees = [];
+        orderFees.forEach((fee) => {
+            try {
+                if (fee.feeId && fee.quantity && fee.unitAmount) {
+                    const originalFee = this.createOriginalFeeFromOrderFee(fee, orderReferenceId, configurationManager);
+                    if (originalFee) {
+                        convertedFees.push(originalFee);
+                    }
+                }
+            }
+            catch (error) {
+                logger.warn(`Failed to process original fee ${fee.feeId}: ${error}`);
+            }
+        });
+        return convertedFees;
+    }
+    createOriginalFeeFromOrderFee(orderFee, orderReferenceId, configurationManager) {
+        const feeLine = utility_1.convertOrderFee(orderFee, orderReferenceId, configurationManager);
+        // Defensive check: convertOrderFee can return undefined if orderFee is missing required properties
+        if (!feeLine) {
+            logger.warn(`convertOrderFee returned undefined for fee ${orderFee.feeId}`);
+            return undefined;
+        }
+        const originalFeeAmount = scp_component_business_core_1.Money.fromIMoney(orderFee.extendedNetAmount);
+        const currency = orderFee.extendedNetAmount.currency;
+        const previouslyRefundedAmount = utility_1.calculatePreviouslyRefundedAmount(orderFee.amountModifiers, currency);
+        const refundableAmount = originalFeeAmount.minus(previouslyRefundedAmount);
+        const refundedAmount = new scp_component_business_core_1.Money("0", originalFeeAmount.currency);
+        const refundAllowed = this.isFeeRefundAllowed(orderFee, configurationManager);
+        return {
+            originalFeeAmount,
+            refundedAmount,
+            previouslyRefundedAmount,
+            refundableAmount,
+            refundAllowed: refundAllowed,
+            feeId: feeLine.feeId,
+            feeType: feeLine.feeType,
+            customFeeType: feeLine.customFeeType,
+            description: feeLine.description,
+            longDescription: feeLine.longDescription,
+            feeLine: feeLine,
+        };
+    }
+    isFeeRefundAllowed(orderFee, configurationManager) {
+        var _a, _b, _c, _d, _e;
+        let refundAllowed = false;
+        if (orderFee.feeType === scp_types_commerce_transaction_1.FeeType.Shipping) {
+            const allowRefundOrderShippingFee = (_d = (_c = (_b = (_a = configurationManager.getFunctionalBehaviorValues()) === null || _a === void 0 ? void 0 : _a.omniChannelBehaviors) === null || _b === void 0 ? void 0 : _b.orders) === null || _c === void 0 ? void 0 : _c.shippingFeeRefundRules) === null || _d === void 0 ? void 0 : _d.allowRefundOrderShippingFee;
+            refundAllowed = allowRefundOrderShippingFee === true;
+        }
+        else {
+            const feeDefinition = utility_1.getFeeDefinitionByFeeId(orderFee.feeId, configurationManager);
+            refundAllowed = ((_e = feeDefinition) === null || _e === void 0 ? void 0 : _e.returnRule) !== configuration_1.ReturnRule.NonReturnable;
+        }
+        return refundAllowed;
+    }
+}
+exports.OrderHandlingSession = OrderHandlingSession;
+// ============================================================================
+// JSON Restoration Helper Functions
+// ============================================================================
+function createOrderInformationCollectionFromJson(jsonArray) {
+    if (!jsonArray || jsonArray.length === 0) {
+        return [];
+    }
+    return jsonArray.map((jsonOrderInfo) => createOrderInformationFromJson(jsonOrderInfo)).filter(Boolean);
+}
+function createOrderInformationFromJson(jsonObject) {
+    if (!jsonObject) {
+        return undefined;
+    }
+    return {
+        orderReferenceId: jsonObject.orderReferenceId,
+        customerOrder: jsonObject.customerOrder,
+        originalFees: createOriginalFeesFromJson(jsonObject.originalFees),
+        originalTenders: jsonObject.originalTenders,
+        informationTimestamp: jsonObject.informationTimestamp
+            ? new Date(jsonObject.informationTimestamp)
+            : undefined,
+    };
+}
+function createOriginalFeesFromJson(jsonArray) {
+    if (!jsonArray || jsonArray.length === 0) {
+        return undefined;
+    }
+    return jsonArray.map((jsonFee) => createOriginalFeeFromJson(jsonFee));
+}
+function createOriginalFeeFromJson(jsonObject) {
+    return {
+        originalFeeAmount: jsonObject.originalFeeAmount && scp_component_business_core_1.Money.fromIMoney(jsonObject.originalFeeAmount),
+        refundedAmount: jsonObject.refundedAmount && scp_component_business_core_1.Money.fromIMoney(jsonObject.refundedAmount),
+        previouslyRefundedAmount: jsonObject.previouslyRefundedAmount && scp_component_business_core_1.Money.fromIMoney(jsonObject.previouslyRefundedAmount),
+        refundableAmount: jsonObject.refundableAmount && scp_component_business_core_1.Money.fromIMoney(jsonObject.refundableAmount),
+        refundAllowed: jsonObject.refundAllowed,
+        feeId: jsonObject.feeId,
+        feeType: jsonObject.feeType,
+        customFeeType: jsonObject.customFeeType,
+        description: jsonObject.description,
+        longDescription: jsonObject.longDescription,
+        feeLine: jsonObject.feeLine,
+    };
+}
+//# sourceMappingURL=OrderHandlingSession.js.map

package/lib/domain/model/fee/FeeLine.d.ts

@@ -190,6 +190,7 @@ export declare function isTransactionFeeLine(transactionLine: ITransactionLine):
 export declare function isTransactionFeeRefundLine(transactionLine: ITransactionLine): transactionLine is FeeLine;
 export declare function isBagFeeLine(transactionLine: ITransactionLine): transactionLine is FeeLine;
 export declare function isShippingFeeLine(transactionLine: ITransactionLine): transactionLine is FeeLine;
+export declare function isShippingFeeRefundLine(transactionLine: ITransactionLine): transactionLine is FeeLine;
 export declare function isDeliveryFeeLine(transactionLine: ITransactionLine): transactionLine is FeeLine;
 export declare function isItemFeeLine(transactionLine: ITransactionLine): transactionLine is FeeLine;
 export declare function isItemFeeRefundLine(transactionLine: ITransactionLine): transactionLine is FeeLine;

package/lib/domain/model/fee/FeeLine.js

@@ -742,6 +742,14 @@ function isShippingFeeLine(transactionLine) {
     return isTransactionFeeLine(transactionLine) && transactionLine.feeType === scp_types_commerce_transaction_1.FeeType.Shipping;
 }
 exports.isShippingFeeLine = isShippingFeeLine;
+function isShippingFeeRefundLine(transactionLine) {
+    if (!isTransactionFeeRefundLine(transactionLine)) {
+        return false;
+    }
+    const feeLine = transactionLine;
+    return feeLine.feeType === scp_types_commerce_transaction_1.FeeType.Shipping && !!feeLine.orderReferenceId;
+}
+exports.isShippingFeeRefundLine = isShippingFeeRefundLine;
 function isDeliveryFeeLine(transactionLine) {
     return isTransactionFeeLine(transactionLine) && transactionLine.feeType === scp_types_commerce_transaction_1.FeeType.Delivery;
 }

package/lib/domain/model/index.d.ts

@@ -111,3 +111,4 @@ export * from "./IReceipt";
 export * from "./storeGoals/";
 export * from "./IStoreItemSummary";
 export * from "./PaymentFunctionSession";
+export * from "./OrderHandlingSession";

package/lib/domain/model/index.js

@@ -95,4 +95,5 @@ __export(require("./taxRecord/"));
 __export(require("./taxLottery/"));
 __export(require("./lottery/"));
 __export(require("./PaymentFunctionSession"));
+__export(require("./OrderHandlingSession"));
 //# sourceMappingURL=index.js.map

package/lib/domain/utility/feeRefundUtils.d.ts

@@ -0,0 +1,20 @@
+import { Money } from "@aptos-scp/scp-component-business-core";
+import { AmountModifier } from "@aptos-scp/scp-types-orders";
+/**
+ * Calculates the total amount previously refunded from a fee's amountModifiers.
+ * Only counts modifiers with "Subtract" action code AND a known refund code
+ * (SSARefund, NonSSAShippingAppeasement) to avoid counting other types of subtractions.
+ *
+ * @param amountModifiers - The array of amount modifiers from the order fee
+ * @param currency - The currency code for creating Money objects
+ * @returns The total previously refunded amount as a Money object
+ */
+export declare function calculatePreviouslyRefundedAmount(amountModifiers: AmountModifier[] | undefined, currency: string): Money;
+/**
+ * Calculates the refundable amount remaining after subtracting previously refunded amounts.
+ *
+ * @param originalAmount - The original fee amount
+ * @param previouslyRefundedAmount - The amount already refunded
+ * @returns The remaining refundable amount as a Money object
+ */
+export declare function calculateRefundableAmount(originalAmount: Money, previouslyRefundedAmount: Money): Money;

package/lib/domain/utility/feeRefundUtils.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const scp_component_business_core_1 = require("@aptos-scp/scp-component-business-core");
+/**
+ * Known refund codes that identify legitimate fee refunds/credits.
+ * - SSARefund: Refunds generated through Store Selling App return flow
+ * - NonSSAShippingAppeasement: Shipping fee credits/appeasements from external OMS
+ */
+const KNOWN_REFUND_CODES = ["SSARefund", "NonSSAShippingAppeasement"];
+/**
+ * Checks if an AmountModifier represents a known refund/credit operation.
+ * Checks controlledOperation.reason.code first (more universal across OMS implementations),
+ * then falls back to amountModificationRule.name.
+ *
+ * @param modifier - The amount modifier to check
+ * @returns true if the modifier has a known refund code
+ */
+function isKnownRefundModifier(modifier) {
+    var _a, _b, _c;
+    // Primary: Check controlledOperation.reason.code (more universal across OMS implementations)
+    const reasonCode = (_b = (_a = modifier.controlledOperation) === null || _a === void 0 ? void 0 : _a.reason) === null || _b === void 0 ? void 0 : _b.code;
+    if (reasonCode && KNOWN_REFUND_CODES.includes(reasonCode)) {
+        return true;
+    }
+    // Fallback: Check amountModificationRule.name
+    const ruleName = (_c = modifier.amountModificationRule) === null || _c === void 0 ? void 0 : _c.name;
+    if (ruleName && KNOWN_REFUND_CODES.includes(ruleName)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Calculates the total amount previously refunded from a fee's amountModifiers.
+ * Only counts modifiers with "Subtract" action code AND a known refund code
+ * (SSARefund, NonSSAShippingAppeasement) to avoid counting other types of subtractions.
+ *
+ * @param amountModifiers - The array of amount modifiers from the order fee
+ * @param currency - The currency code for creating Money objects
+ * @returns The total previously refunded amount as a Money object
+ */
+function calculatePreviouslyRefundedAmount(amountModifiers, currency) {
+    if (!amountModifiers || amountModifiers.length === 0) {
+        return new scp_component_business_core_1.Money("0", currency);
+    }
+    return amountModifiers
+        .filter((modifier) => modifier.actionCode === "Subtract" && isKnownRefundModifier(modifier))
+        .reduce((total, modifier) => {
+        return total.plus(scp_component_business_core_1.Money.fromIMoney(modifier.amount));
+    }, new scp_component_business_core_1.Money("0", currency));
+}
+exports.calculatePreviouslyRefundedAmount = calculatePreviouslyRefundedAmount;
+/**
+ * Calculates the refundable amount remaining after subtracting previously refunded amounts.
+ *
+ * @param originalAmount - The original fee amount
+ * @param previouslyRefundedAmount - The amount already refunded
+ * @returns The remaining refundable amount as a Money object
+ */
+function calculateRefundableAmount(originalAmount, previouslyRefundedAmount) {
+    return originalAmount.minus(previouslyRefundedAmount);
+}
+exports.calculateRefundableAmount = calculateRefundableAmount;
+//# sourceMappingURL=feeRefundUtils.js.map

package/lib/domain/utility/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./utils";
 export * from "./orderUtils";
+export * from "./orderFeeUtils";
 export * from "./itemImageUtils";
+export * from "./feeRefundUtils";

package/lib/domain/utility/index.js

@@ -5,5 +5,7 @@ function __export(m) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __export(require("./utils"));
 __export(require("./orderUtils"));
+__export(require("./orderFeeUtils"));
 __export(require("./itemImageUtils"));
+__export(require("./feeRefundUtils"));
 //# sourceMappingURL=index.js.map