@aglyn/plugins-commerce 1.0.0-beta.229 → 1.0.0-beta.231

package/src/lib/server/pos-return.js

@@ -0,0 +1,891 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { claimAttempt } from "@aglyn/aglyn/server";
+import { createResourceUid } from "@aglyn/aglyn/app-utils/create-resource-uid";
+import { nameSearchKey } from "@aglyn/aglyn/app-utils/name-search";
+import { recordPluginPersonRefund } from "@aglyn/aglyn/plugin-manager/plugin-person-records";
+import { reverseOrderConversion } from "@aglyn/aglyn/plugin-manager/plugin-conversion-credit";
+import * as CommerceModel from "../model/index.js";
+import { planPosReturn, posMoney, posRefundableByTender, posReturnedQuantities, posReturnLineValues, posTenderLabel, POS_STRIPE_TENDERS, splitPosRefund } from "../model/commerce-pos-ops.js";
+import { ORDER_REFUNDED_EVENT, RETURN_REFUNDED_EVENT } from "../model/order-events.js";
+import { raiseOrderEvent } from "./order-events.js";
+import { applyGiftCardRiskToOrder } from "./gift-card-risk.js";
+import { notifyOrderBuyer } from "./order-notifications.js";
+import { decidePosRefundAuthority } from "./pos-refund-authority.js";
+import { authorizePosOps, defaultPosOpsDeps, posOpsBody, posOpsCleanId, posOpsIdempotencyKey, readPosRegister, isPosManager, resolvePosCashier } from "./pos-ops-gate.js";
+import { createStripeRefund } from "./stripe-refund.js";
+export function defaultPosReturnDeps() {
+    const base = defaultPosOpsDeps();
+    return _extends({}, base, {
+        afterRefund: async (input)=>{
+            const settle = async (label, work)=>{
+                try {
+                    await work();
+                } catch (error) {
+                    console.error(`[pos-return] ${label} failed`, input.orderId, error);
+                }
+            };
+            const hostRef = base.firestore().collection('hosts').doc(input.hostId);
+            if (input.returnedProductIds.length) {
+                await settle('gift card void', ()=>applyGiftCardRiskToOrder({
+                        firestore: base.firestore(),
+                        hostRef,
+                        orderId: input.orderId,
+                        action: _extends({
+                            kind: 'void',
+                            reason: 'refund'
+                        }, input.fullyRefunded ? {} : {
+                            productIds: input.returnedProductIds
+                        })
+                    }));
+            }
+            await settle('person refund', ()=>recordPluginPersonRefund({
+                    hostId: input.hostId,
+                    refId: input.orderId,
+                    email: input.email,
+                    amountCents: input.refundCents,
+                    closedTheSale: input.closedTheOrder
+                }));
+            await settle('conversion reversal', ()=>reverseOrderConversion({
+                    hostId: input.hostId,
+                    orderId: input.orderId,
+                    amountCents: input.refundCents,
+                    closedTheOrder: input.closedTheOrder
+                }));
+            // The same events a refund from the order dialog and a refunded online
+            // return raise, so accounting and the merchant's webhooks hear a
+            // register return too (AGL-3611's events).
+            await settle('refund event', ()=>{
+                var _input_refundIds_;
+                return raiseOrderEvent(ORDER_REFUNDED_EVENT, {
+                    hostId: input.hostId,
+                    orderId: input.orderId,
+                    key: `pos-return:${input.returnId}`,
+                    extra: {
+                        refund: {
+                            id: (_input_refundIds_ = input.refundIds[0]) != null ? _input_refundIds_ : null,
+                            amountCents: input.refundCents,
+                            lineItemIds: input.fullLineIndexes,
+                            full: input.fullyRefunded
+                        }
+                    }
+                });
+            });
+            await settle('return event', ()=>{
+                var _input_storeReturn_refundCents;
+                return raiseOrderEvent(RETURN_REFUNDED_EVENT, {
+                    hostId: input.hostId,
+                    orderId: input.orderId,
+                    key: `return-refunded:${input.returnId}`,
+                    extra: {
+                        return: {
+                            id: input.returnId,
+                            status: input.storeReturn.status,
+                            lines: input.storeReturn.lines.map((line)=>_extends({}, line)),
+                            refundCents: (_input_storeReturn_refundCents = input.storeReturn.refundCents) != null ? _input_storeReturn_refundCents : null
+                        }
+                    }
+                });
+            });
+            await settle('buyer notice', ()=>notifyOrderBuyer({
+                    hostId: input.hostId,
+                    orderId: input.orderId
+                }, 'refunded', {
+                    refundId: '',
+                    refundCents: input.refundCents,
+                    refundLineIndexes: input.lineIndexes,
+                    fullyRefunded: input.fullyRefunded
+                }));
+        }
+    });
+}
+/** The statuses a return may be taken against. */ const RETURNABLE = new Set([
+    'paid',
+    'partially_fulfilled',
+    'fulfilled',
+    'delivered'
+]);
+/** One order as the return dialog lists it. */ function returnSummary(id, raw, held = []) {
+    var _order_number, _order_channel, _order_createdAtMs, _order_customerEmail, _order_customerName, _ref, _ref1, _order_refundedCents, _order_lineItems;
+    var _order_totals;
+    const order = CommerceModel.liftLegacyOrder(raw);
+    const values = posReturnLineValues(order);
+    const returned = posReturnedQuantities(order);
+    return {
+        id,
+        number: (_order_number = order['number']) != null ? _order_number : null,
+        label: CommerceModel.formatOrderNumber(order, id),
+        status: order['status'],
+        channel: (_order_channel = order['channel']) != null ? _order_channel : 'online',
+        createdAtMs: Number((_order_createdAtMs = order['createdAtMs']) != null ? _order_createdAtMs : 0),
+        customerEmail: (_order_customerEmail = order['customerEmail']) != null ? _order_customerEmail : null,
+        customerName: (_order_customerName = order['customerName']) != null ? _order_customerName : null,
+        totalCents: Number((_ref = (_ref1 = (_order_totals = order.totals) == null ? void 0 : _order_totals.totalCents) != null ? _ref1 : order.amountCents) != null ? _ref : 0),
+        refundedCents: Number((_order_refundedCents = order.refundedCents) != null ? _order_refundedCents : 0),
+        returnable: RETURNABLE.has(String(order['status'])),
+        lines: ((_order_lineItems = order.lineItems) != null ? _order_lineItems : []).map((line, index)=>{
+            var _ref, _ref1, _ref2, _returned_index, _held_index, _values_index;
+            return {
+                index,
+                name: String((_ref = line == null ? void 0 : line.name) != null ? _ref : ''),
+                variantLabel: (_ref1 = line == null ? void 0 : line.variantLabel) != null ? _ref1 : null,
+                quantity: Math.max(1, Math.round(Number((_ref2 = line == null ? void 0 : line.quantity) != null ? _ref2 : 1))),
+                returned: (_returned_index = returned[index]) != null ? _returned_index : 0,
+                // Units an online return holds or already took (AGL-3611).
+                held: (_held_index = held[index]) != null ? _held_index : 0,
+                valueCents: (_values_index = values[index]) != null ? _values_index : 0
+            };
+        }),
+        tenders: posRefundableByTender(order).map((tender)=>({
+                id: tender.id,
+                method: tender.method,
+                label: posTenderLabel(tender),
+                amountCents: tender.amountCents,
+                refundableCents: tender.refundableCents
+            }))
+    };
+}
+async function findOrders(hostRef, rawText) {
+    var _snapshot_data;
+    const text = String(rawText != null ? rawText : '').trim().slice(0, 200);
+    if (!text) return [];
+    const orders = hostRef.collection('orders');
+    const digits = text.replace(/^#/, '');
+    if (/^\d{1,12}$/.test(digits)) {
+        const snapshot = await orders.where('number', '==', Number(digits)).limit(5).get();
+        return snapshot.docs.map((doc)=>{
+            var _doc_data;
+            return {
+                id: doc.id,
+                data: (_doc_data = doc.data()) != null ? _doc_data : {}
+            };
+        });
+    }
+    if (text.includes('@')) {
+        const snapshot = await orders.where('customerEmailLower', '==', nameSearchKey(text)).orderBy('createdAtMs', 'desc').limit(10).get();
+        return snapshot.docs.map((doc)=>{
+            var _doc_data;
+            return {
+                id: doc.id,
+                data: (_doc_data = doc.data()) != null ? _doc_data : {}
+            };
+        });
+    }
+    const id = posOpsCleanId(text);
+    if (!id) return [];
+    const snapshot = await orders.doc(id).get();
+    return snapshot.exists ? [
+        {
+            id,
+            data: (_snapshot_data = snapshot.data()) != null ? _snapshot_data : {}
+        }
+    ] : [];
+}
+function parsePicks(raw) {
+    if (!Array.isArray(raw)) return [];
+    return raw.slice(0, 200).map((entry)=>({
+            index: Number(entry == null ? void 0 : entry.index),
+            quantity: Number(entry == null ? void 0 : entry.quantity)
+        }));
+}
+function parseSplit(raw) {
+    if (!Array.isArray(raw) || !raw.length) return null;
+    return raw.slice(0, 20).map((entry)=>{
+        var _ref;
+        return {
+            paymentId: String((_ref = entry == null ? void 0 : entry.paymentId) != null ? _ref : ''),
+            amountCents: Number(entry == null ? void 0 : entry.amountCents)
+        };
+    });
+}
+export async function handlePosReturn(deps, req) {
+    var _body_action, _body_reason, _register_data_openShiftId;
+    if (req.method !== 'POST') return {
+        status: 405,
+        body: {
+            error: 'Method not allowed'
+        }
+    };
+    const body = posOpsBody(req);
+    const gate = await authorizePosOps(deps, req, body['hostId']);
+    if ('error' in gate) return {
+        status: gate.status,
+        body: {
+            error: gate.error
+        }
+    };
+    const staff = gate.staff;
+    const action = String((_body_action = body['action']) != null ? _body_action : '');
+    if (action === 'find') {
+        const found = await findOrders(staff.hostRef, body['text']);
+        const held = await Promise.all(found.map(async (entry)=>unitsHeldByOnlineReturns((await staff.hostRef.collection('returns').where('orderId', '==', entry.id).get()).docs)));
+        return {
+            status: 200,
+            body: {
+                orders: found.map((entry, at)=>returnSummary(entry.id, entry.data, held[at]))
+            }
+        };
+    }
+    if (action !== 'refund') return {
+        status: 400,
+        body: {
+            error: 'Unknown action'
+        }
+    };
+    const register = await readPosRegister(staff, body['registerId']);
+    if ('error' in register) return {
+        status: register.status,
+        body: {
+            error: register.error
+        }
+    };
+    const registerId = register.ref.id;
+    const orderId = posOpsCleanId(body['orderId']);
+    if (!orderId) return {
+        status: 400,
+        body: {
+            error: 'Missing orderId'
+        }
+    };
+    const idempotencyKey = posOpsIdempotencyKey(req);
+    if (!idempotencyKey) {
+        return {
+            status: 400,
+            body: {
+                error: 'A refund needs an Idempotency-Key header.'
+            }
+        };
+    }
+    const picks = parsePicks(body['lines']);
+    const requestedSplit = parseSplit(body['tenders']);
+    const restock = body['restock'] !== false;
+    const reason = String((_body_reason = body['reason']) != null ? _body_reason : '').trim().slice(0, 200);
+    const reasonCode = CommerceModel.RETURN_REASONS.includes(body['reasonCode']) ? body['reasonCode'] : 'other';
+    const firestore = deps.firestore();
+    const orderRef = staff.hostRef.collection('orders').doc(orderId);
+    const storeReturns = staff.hostRef.collection('returns').where('orderId', '==', orderId);
+    // 1. Every refusal that needs no money to move.
+    const snapshot = await orderRef.get();
+    if (!snapshot.exists) return {
+        status: 404,
+        body: {
+            error: 'Unknown order'
+        }
+    };
+    const order = CommerceModel.liftLegacyOrder(snapshot.data());
+    if (!RETURNABLE.has(String(order['status']))) {
+        return {
+            status: 409,
+            body: {
+                error: `Orders in "${order['status']}" cannot be returned.`
+            }
+        };
+    }
+    if (CommerceModel.orderDisputeBlocksRefund(order)) {
+        return {
+            status: 409,
+            body: {
+                error: 'A chargeback is open on this order, so it was not refunded. Respond to the ' + 'dispute or accept it in the Stripe dashboard first.'
+            }
+        };
+    }
+    const plan = planPosReturn(order, picks, unitsHeldByOnlineReturns((await storeReturns.get()).docs));
+    if ('error' in plan) return {
+        status: 400,
+        body: {
+            error: plan.error
+        }
+    };
+    const split = splitPosRefund(order, plan.refundCents, requestedSplit);
+    if ('error' in split) return {
+        status: 400,
+        body: {
+            error: split.error
+        }
+    };
+    const cashier = await resolvePosCashier(deps, staff, registerId, body['cashierAssertion']);
+    // The limit is the person at the till's: a PIN-switched cashier is held
+    // to it even on a device a workspace admin signed in on.
+    const cashierIsManager = cashier.cashierId === staff.uid ? staff.isManager : await memberIsPosManager(deps, staff.hostRef, staff.hostId, cashier.cashierId);
+    const authority = await decidePosRefundAuthority(deps, {
+        hostId: staff.hostId,
+        hostRef: staff.hostRef,
+        registerId,
+        refundCents: plan.refundCents,
+        limitCents: staff.settings.refundLimitCents,
+        isManager: cashierIsManager,
+        managerAssertion: body['managerAssertion']
+    });
+    if ('body' in authority) return {
+        status: 403,
+        body: authority.body
+    };
+    const needsCash = split.allocations.some((slice)=>slice.method === 'cash');
+    const needsStripe = split.allocations.some((slice)=>POS_STRIPE_TENDERS.has(slice.method));
+    const openShiftId = String((_register_data_openShiftId = register.data['openShiftId']) != null ? _register_data_openShiftId : '') || null;
+    if (needsCash && !openShiftId && staff.settings.requireOpenShift) {
+        return {
+            status: 409,
+            body: {
+                error: 'Open a shift before paying cash out of the drawer.'
+            }
+        };
+    }
+    if (needsStripe && !process.env.STRIPE_SECRET_KEY) {
+        return {
+            status: 501,
+            body: {
+                error: 'Payments are not configured.'
+            }
+        };
+    }
+    // 2. The attempt claim.
+    const claimed = await claimAttempt(firestore, {
+        kind: 'pos-return',
+        scopeId: staff.hostId,
+        orgId: staff.orgId,
+        key: `${orderId}:${idempotencyKey}`,
+        busyMessage: 'This return is already being refunded'
+    });
+    if ('replay' in claimed) return {
+        status: claimed.replay.status,
+        body: claimed.replay.body
+    };
+    const claim = claimed.claim;
+    let reserved;
+    try {
+        reserved = await firestore.runTransaction(async (transaction)=>{
+            var _data, _fresh_refundedCents, _fresh_returnedQuantities, _fresh_posPaymentRefunds;
+            const fresh = CommerceModel.liftLegacyOrder((_data = (await transaction.get(orderRef)).data()) != null ? _data : {});
+            if (!RETURNABLE.has(String(fresh['status']))) {
+                throw new ReturnRefusal(409, `Orders in "${fresh['status']}" cannot be returned.`);
+            }
+            const freshPlan = planPosReturn(fresh, picks, unitsHeldByOnlineReturns((await transaction.get(storeReturns)).docs));
+            if ('error' in freshPlan) throw new ReturnRefusal(409, freshPlan.error);
+            const freshSplit = splitPosRefund(fresh, freshPlan.refundCents, requestedSplit);
+            if ('error' in freshSplit) throw new ReturnRefusal(409, freshSplit.error);
+            const prior = {
+                refundedCents: Number((_fresh_refundedCents = fresh.refundedCents) != null ? _fresh_refundedCents : 0),
+                returnedQuantities: _extends({}, (_fresh_returnedQuantities = fresh.returnedQuantities) != null ? _fresh_returnedQuantities : {}),
+                posPaymentRefunds: _extends({}, (_fresh_posPaymentRefunds = fresh.posPaymentRefunds) != null ? _fresh_posPaymentRefunds : {})
+            };
+            const posPaymentRefunds = _extends({}, prior.posPaymentRefunds);
+            for (const slice of freshSplit.allocations){
+                var _posPaymentRefunds_slice_paymentId;
+                posPaymentRefunds[slice.paymentId] = ((_posPaymentRefunds_slice_paymentId = posPaymentRefunds[slice.paymentId]) != null ? _posPaymentRefunds_slice_paymentId : 0) + slice.amountCents;
+            }
+            transaction.update(orderRef, {
+                refundedCents: prior.refundedCents + freshPlan.refundCents,
+                returnedQuantities: freshPlan.returnedQuantities,
+                posPaymentRefunds
+            });
+            return {
+                refundCents: freshPlan.refundCents,
+                lineCents: freshPlan.lineCents,
+                completedLines: freshPlan.completedLines,
+                allocations: freshSplit.allocations,
+                prior
+            };
+        });
+    } catch (error) {
+        await claim.release();
+        if (error instanceof ReturnRefusal) return {
+            status: error.status,
+            body: {
+                error: error.message
+            }
+        };
+        throw error;
+    }
+    // 4–5. The money, Stripe first.
+    const tenders = posRefundableByTender(order);
+    const tenderOf = (paymentId)=>tenders.find((tender)=>tender.id === paymentId);
+    const ordered = [
+        ...reserved.allocations
+    ].sort((a, b)=>Number(POS_STRIPE_TENDERS.has(b.method)) - Number(POS_STRIPE_TENDERS.has(a.method)));
+    const results = [];
+    for (const allocation of ordered){
+        const tender = tenderOf(allocation.paymentId);
+        const anyMoved = results.some((result)=>result.status === 'refunded');
+        try {
+            if (POS_STRIPE_TENDERS.has(allocation.method)) {
+                var _ref, _order_paymentIntentId;
+                const paymentIntentId = (_ref = tender == null ? void 0 : tender.paymentIntentId) != null ? _ref : String((_order_paymentIntentId = order['paymentIntentId']) != null ? _order_paymentIntentId : '');
+                if (!paymentIntentId) throw new ReturnRefusal(409, 'That card payment has nothing Stripe can refund.');
+                const refund = await createStripeRefund({
+                    paymentIntentId,
+                    amountCents: allocation.amountCents,
+                    idempotencyKey: claim.stripeKey ? `${claim.stripeKey}:${allocation.paymentId}` : null,
+                    metadata: {
+                        hostId: staff.hostId,
+                        orderId,
+                        registerId,
+                        kind: 'pos-return'
+                    },
+                    fetch: deps.fetch
+                });
+                if ('error' in refund) throw new ReturnRefusal(refund.status, refund.error);
+                results.push({
+                    allocation,
+                    status: 'refunded',
+                    refundId: refund.refundId
+                });
+            } else if (allocation.method === 'gift_card') {
+                var _ref1;
+                await creditGiftCard(firestore, staff.hostRef, (_ref1 = tender == null ? void 0 : tender.giftCardId) != null ? _ref1 : '', allocation.amountCents, orderId, deps.now());
+                results.push({
+                    allocation,
+                    status: 'refunded'
+                });
+            } else if (allocation.method === 'folio') {
+                var _ref2, _order_reservationId;
+                await reverseFolio(staff.hostRef, (_ref2 = tender == null ? void 0 : tender.reservationId) != null ? _ref2 : String((_order_reservationId = order['reservationId']) != null ? _order_reservationId : ''), allocation.amountCents, orderId, deps.now());
+                results.push({
+                    allocation,
+                    status: 'refunded'
+                });
+            } else {
+                // Cash: recorded on the drawer with the return itself, below.
+                results.push({
+                    allocation,
+                    status: 'refunded'
+                });
+            }
+        } catch (error) {
+            const message = error instanceof ReturnRefusal ? error.message : 'Refund failed';
+            if (!(error instanceof ReturnRefusal)) console.error('[pos-return] tender failed', allocation, error);
+            if (!anyMoved) {
+                // Nothing has moved: hand the whole reservation back and let the
+                // same attempt be tried again.
+                await firestore.runTransaction(async (transaction)=>{
+                    await transaction.get(orderRef);
+                    transaction.update(orderRef, reserved.prior);
+                }).catch((rollback)=>console.error('[pos-return] rollback failed', orderId, rollback));
+                await claim.release();
+                return {
+                    status: error instanceof ReturnRefusal ? error.status : 502,
+                    body: {
+                        error: message
+                    }
+                };
+            }
+            results.push({
+                allocation,
+                status: 'failed',
+                error: message
+            });
+        }
+    }
+    const failed = results.filter((result)=>result.status === 'failed');
+    const refundedCents = results.filter((result)=>result.status === 'refunded').reduce((sum, result)=>sum + result.allocation.amountCents, 0);
+    const cashCents = results.filter((result)=>result.status === 'refunded' && result.allocation.method === 'cash').reduce((sum, result)=>sum + result.allocation.amountCents, 0);
+    const now = deps.now();
+    // One id names the return under the register (its tenders and shift) and
+    // in the store's returns list beside the online ones (AGL-3611).
+    const returnId = createResourceUid();
+    const returnRef = register.ref.collection('returns').doc(returnId);
+    const storeReturnRef = staff.hostRef.collection('returns').doc(returnId);
+    const orderLabel = CommerceModel.formatOrderNumber(order, orderId);
+    const lines = picks.map((pick, at)=>{
+        var _ref, _reserved_lineCents_at;
+        var _order_lineItems_pick_index, _order_lineItems;
+        return {
+            index: pick.index,
+            quantity: pick.quantity,
+            name: String((_ref = (_order_lineItems = order.lineItems) == null ? void 0 : (_order_lineItems_pick_index = _order_lineItems[pick.index]) == null ? void 0 : _order_lineItems_pick_index.name) != null ? _ref : ''),
+            refundCents: (_reserved_lineCents_at = reserved.lineCents[at]) != null ? _reserved_lineCents_at : 0
+        };
+    });
+    // The record, the drawer, the order: one transaction.
+    let closedTheOrder = false;
+    let fullyRefunded = false;
+    let shiftIdForReturn = null;
+    let storeReturn = null;
+    await firestore.runTransaction(async (transaction)=>{
+        var _freshRegister_get, _data, _fresh_posPaymentRefunds, _fresh_refundedCents, _ref, _ref1, _fresh_returnedQuantities, _fresh_refundedLineItemIds, _order_customerEmail, _order_customerName;
+        var _fresh_totals;
+        const freshRegister = await transaction.get(register.ref);
+        const shiftId = String((_freshRegister_get = freshRegister.get('openShiftId')) != null ? _freshRegister_get : '') || null;
+        const shiftRef = shiftId ? register.ref.collection('shifts').doc(shiftId) : null;
+        const shiftSnapshot = shiftRef ? await transaction.get(shiftRef) : null;
+        const fresh = CommerceModel.liftLegacyOrder((_data = (await transaction.get(orderRef)).data()) != null ? _data : {});
+        const shiftOpen = Boolean((shiftSnapshot == null ? void 0 : shiftSnapshot.exists) && shiftSnapshot.get('status') === 'open');
+        shiftIdForReturn = shiftOpen ? shiftId : null;
+        // Hand back what a failed card did not refund.
+        const failedCents = failed.reduce((sum, result)=>sum + result.allocation.amountCents, 0);
+        const posPaymentRefunds = _extends({}, (_fresh_posPaymentRefunds = fresh.posPaymentRefunds) != null ? _fresh_posPaymentRefunds : {});
+        for (const result of failed){
+            var _posPaymentRefunds_result_allocation_paymentId;
+            posPaymentRefunds[result.allocation.paymentId] = Math.max(0, ((_posPaymentRefunds_result_allocation_paymentId = posPaymentRefunds[result.allocation.paymentId]) != null ? _posPaymentRefunds_result_allocation_paymentId : 0) - result.allocation.amountCents);
+        }
+        const orderRefunded = Math.max(0, Number((_fresh_refundedCents = fresh.refundedCents) != null ? _fresh_refundedCents : 0) - failedCents);
+        const totalCents = Number((_ref = (_ref1 = (_fresh_totals = fresh.totals) == null ? void 0 : _fresh_totals.totalCents) != null ? _ref1 : fresh.amountCents) != null ? _ref : 0);
+        fullyRefunded = orderRefunded >= totalCents && totalCents > 0;
+        closedTheOrder = fullyRefunded && fresh['status'] !== 'refunded' && CommerceModel.canTransitionOrder(fresh['status'], 'refunded');
+        const completedLines = Object.entries((_fresh_returnedQuantities = fresh.returnedQuantities) != null ? _fresh_returnedQuantities : {}).filter(([index, count])=>{
+            var _ref;
+            var _fresh_lineItems_Number, _fresh_lineItems;
+            return count >= Math.max(1, Number((_ref = (_fresh_lineItems = fresh.lineItems) == null ? void 0 : (_fresh_lineItems_Number = _fresh_lineItems[Number(index)]) == null ? void 0 : _fresh_lineItems_Number.quantity) != null ? _ref : 1));
+        }).map(([index])=>Number(index));
+        const tenderWords = results.map((result)=>{
+            var _tenderOf;
+            return `${posMoney(result.allocation.amountCents)} to ${posTenderLabel((_tenderOf = tenderOf(result.allocation.paymentId)) != null ? _tenderOf : {
+                method: result.allocation.method
+            })}${result.status === 'failed' ? ' (FAILED)' : ''}`;
+        }).join(', ');
+        const units = picks.reduce((sum, pick)=>sum + pick.quantity, 0);
+        transaction.update(orderRef, _extends({
+            refundedCents: orderRefunded,
+            posPaymentRefunds
+        }, closedTheOrder ? {
+            status: 'refunded'
+        } : {}, completedLines.length ? {
+            refundedLineItemIds: [
+                ...new Set([
+                    ...(_fresh_refundedLineItemIds = fresh.refundedLineItemIds) != null ? _fresh_refundedLineItemIds : [],
+                    ...completedLines
+                ])
+            ].sort((a, b)=>a - b)
+        } : {}, {
+            timeline: CommerceModel.appendOrderEvent(fresh, 'refund', `Returned at the register: ${units} ${units === 1 ? 'item' : 'items'}, ${tenderWords}` + (restock ? '; restocked' : '') + (authority.approvedBy ? '; approved by a manager' : ''), now)
+        }));
+        const record = _extends({
+            hostId: staff.hostId,
+            registerId,
+            orderId
+        }, typeof order['number'] === 'number' ? {
+            orderNumber: order['number']
+        } : {}, shiftOpen && shiftId ? {
+            shiftId
+        } : {}, {
+            lines,
+            refundedCents,
+            tenders: results.map((result)=>_extends({}, result.allocation, {
+                    status: result.status
+                }, result.refundId ? {
+                    refundId: result.refundId
+                } : {}, result.error ? {
+                    error: result.error
+                } : {})),
+            restocked: restock
+        }, register.data['locationId'] ? {
+            locationId: String(register.data['locationId'])
+        } : {}, {
+            cashierId: cashier.cashierId
+        }, authority.approvedBy ? {
+            approvedBy: authority.approvedBy
+        } : {}, reason ? {
+            reason
+        } : {}, {
+            status: failed.length ? 'partial' : 'refunded',
+            atMs: now
+        });
+        transaction.create(returnRef, record);
+        const restockedLines = picks.map((pick)=>({
+                lineItemId: pick.index,
+                quantity: pick.quantity
+            }));
+        const registerLocationId = register.data['locationId'] ? String(register.data['locationId']) : undefined;
+        storeReturn = _extends({
+            orderId,
+            orderNumber: orderLabel,
+            customerEmail: (_order_customerEmail = order['customerEmail']) != null ? _order_customerEmail : null,
+            customerName: (_order_customerName = order['customerName']) != null ? _order_customerName : null,
+            lines: picks.map((pick)=>({
+                    lineItemId: pick.index,
+                    quantity: pick.quantity,
+                    reason: reasonCode
+                })),
+            status: 'refunded',
+            requestedBy: 'merchant',
+            source: 'register',
+            registerId
+        }, reason ? {
+            merchantNote: reason
+        } : {}, restock ? {
+            restock: _extends({
+                lines: restockedLines
+            }, registerLocationId ? {
+                locationId: registerLocationId
+            } : {}, {
+                atMs: now
+            })
+        } : {}, {
+            refundedAtMs: now,
+            refundCents: refundedCents,
+            timeline: [
+                {
+                    atMs: now,
+                    event: 'refunded',
+                    detail: `At the register${failed.length ? `; ${posMoney(failed.reduce((sum, result)=>sum + result.allocation.amountCents, 0))} still owed` : ''}`
+                }
+            ],
+            createdAtMs: now,
+            updatedAtMs: now
+        });
+        transaction.create(storeReturnRef, storeReturn);
+        if (shiftOpen && shiftRef && cashCents > 0) {
+            const event = {
+                id: returnRef.id,
+                type: 'refund',
+                amountCents: cashCents,
+                reason: `Return ${orderLabel}`,
+                by: cashier.cashierId,
+                atMs: now,
+                orderId
+            };
+            const cashEvents = Array.isArray(shiftSnapshot == null ? void 0 : shiftSnapshot.get('cashEvents')) ? shiftSnapshot.get('cashEvents') : [];
+            transaction.update(shiftRef, {
+                cashEvents: [
+                    ...cashEvents,
+                    event
+                ]
+            });
+        }
+    });
+    // Restock what came back to the register's location.
+    let restockedUnits = 0;
+    if (restock) {
+        var _ref3, _register_data_locationId;
+        restockedUnits = await restockReturn(firestore, staff.hostRef, order, picks, String((_ref3 = (_register_data_locationId = register.data['locationId']) != null ? _register_data_locationId : order['locationId']) != null ? _ref3 : '') || undefined, orderId, now).catch((error)=>{
+            console.error('[pos-return] restock failed', orderId, error);
+            return 0;
+        });
+    }
+    // The drawer opens for the cash being handed back.
+    if (cashCents > 0) {
+        await deps.printer.kickDrawer({
+            hostId: staff.hostId,
+            registerId,
+            reason: 'cash_refund',
+            causeId: returnRef.id,
+            createdBy: cashier.cashierId
+        });
+    }
+    const payload = {
+        returnId: returnRef.id,
+        refundedCents,
+        outstandingCents: failed.reduce((sum, result)=>sum + result.allocation.amountCents, 0),
+        partial: failed.length > 0,
+        tenders: results.map((result)=>{
+            var _tenderOf;
+            return _extends({
+                method: result.allocation.method,
+                label: posTenderLabel((_tenderOf = tenderOf(result.allocation.paymentId)) != null ? _tenderOf : {
+                    method: result.allocation.method
+                }),
+                amountCents: result.allocation.amountCents,
+                status: result.status
+            }, result.error ? {
+                error: result.error
+            } : {});
+        }),
+        cashOutCents: cashCents,
+        restockedUnits,
+        shiftId: shiftIdForReturn,
+        fullyRefunded
+    };
+    await claim.record(200, payload);
+    if (refundedCents > 0) {
+        var _order_customerEmail;
+        await deps.afterRefund({
+            hostId: staff.hostId,
+            orderId,
+            email: (_order_customerEmail = order['customerEmail']) != null ? _order_customerEmail : null,
+            refundCents: refundedCents,
+            closedTheOrder,
+            fullyRefunded,
+            returnedProductIds: [
+                ...new Set(picks.map((pick)=>{
+                    var _ref;
+                    var _order_lineItems_pick_index, _order_lineItems;
+                    return String((_ref = (_order_lineItems = order.lineItems) == null ? void 0 : (_order_lineItems_pick_index = _order_lineItems[pick.index]) == null ? void 0 : _order_lineItems_pick_index.productId) != null ? _ref : '');
+                }).filter(Boolean))
+            ],
+            lineIndexes: picks.map((pick)=>pick.index),
+            fullLineIndexes: reserved.completedLines,
+            returnId,
+            storeReturn: storeReturn,
+            refundIds: results.flatMap((result)=>result.refundId ? [
+                    result.refundId
+                ] : [])
+        });
+    }
+    return {
+        status: 200,
+        body: payload
+    };
+}
+/**
+ * Units per order line that the store's OTHER returns — the online returns
+ * flow (AGL-3611) — hold or already took back. The register's own returns are
+ * left out: `returnedQuantities` on the order already counts them.
+ */ export function unitsHeldByOnlineReturns(docs) {
+    const held = [];
+    for (const doc of docs){
+        var _doc_data, _entry_lines;
+        const entry = (_doc_data = doc.data()) != null ? _doc_data : {};
+        if (entry.source === 'register' || !CommerceModel.returnHoldsUnits(entry)) continue;
+        for (const line of (_entry_lines = entry.lines) != null ? _entry_lines : []){
+            var _held_index;
+            const index = Number(line == null ? void 0 : line.lineItemId);
+            if (!Number.isInteger(index) || index < 0) continue;
+            held[index] = ((_held_index = held[index]) != null ? _held_index : 0) + Math.max(0, Math.floor(Number(line == null ? void 0 : line.quantity) || 0));
+        }
+    }
+    return held;
+}
+/** Whether a member is a workspace admin and this site's admin, asked now. */ async function memberIsPosManager(deps, hostRef, hostId, uid) {
+    var _host_get;
+    const host = await hostRef.get();
+    const role = ((_host_get = host.get('memberRoles')) != null ? _host_get : {})[uid];
+    return isPosManager(role, await deps.membership(uid, hostId));
+}
+let ReturnRefusal = class ReturnRefusal extends Error {
+    constructor(status, message){
+        super(message), this.status = status;
+    }
+};
+/**
+ * Store credit back on the card it came off. A voided or frozen card takes
+ * nothing: a void is a fraud or refund decision, and re-crediting it would
+ * undo that decision by the back door.
+ */ async function creditGiftCard(firestore, hostRef, code, amountCents, orderId, now) {
+    const id = String(code != null ? code : '').trim();
+    if (!id || id.includes('/') || id.length > 64) throw new ReturnRefusal(409, 'That gift card payment does not name its card.');
+    const ref = hostRef.collection('giftCards').doc(id);
+    await firestore.runTransaction(async (transaction)=>{
+        var _card_get;
+        const card = await transaction.get(ref);
+        if (!card.exists) throw new ReturnRefusal(409, 'That gift card no longer exists.');
+        if (card.get('voidedAtMs') != null || card.get('frozenAtMs') != null) {
+            throw new ReturnRefusal(409, 'That gift card is voided or frozen, so it cannot take a refund.');
+        }
+        transaction.update(ref, {
+            balanceCents: Math.max(0, Math.round(Number((_card_get = card.get('balanceCents')) != null ? _card_get : 0))) + amountCents,
+            lastCreditAtMs: now,
+            lastCreditOrderId: orderId
+        });
+    });
+}
+/** A room charge taken back: a negative line on the same stay's folio. */ async function reverseFolio(hostRef, reservationId, amountCents, orderId, now) {
+    const id = posOpsCleanId(reservationId);
+    if (!id) throw new ReturnRefusal(409, 'That room charge does not name its stay.');
+    const ref = hostRef.collection('reservations').doc(id);
+    const firestore = hostRef.firestore;
+    await firestore.runTransaction(async (transaction)=>{
+        const stay = await transaction.get(ref);
+        if (!stay.exists) throw new ReturnRefusal(409, 'That stay no longer exists.');
+        const folio = Array.isArray(stay.get('folio')) ? stay.get('folio') : [];
+        transaction.update(ref, {
+            folio: [
+                ...folio,
+                {
+                    orderId,
+                    amountCents: -amountCents,
+                    note: 'Return at the register',
+                    atMs: now
+                }
+            ]
+        });
+    });
+}
+/**
+ * The returned units back on the shelf, at the register's location, with an
+ * adjustment row each so the stock history says why the count went up.
+ * Only variants that track stock move.
+ */ async function restockReturn(firestore, hostRef, order, picks, locationId, orderId, now) {
+    const byProduct = new Map();
+    for (const pick of picks){
+        var _order_lineItems, _ref, _byProduct_get;
+        const line = ((_order_lineItems = order.lineItems) != null ? _order_lineItems : [])[pick.index];
+        const productId = String((_ref = line == null ? void 0 : line['productId']) != null ? _ref : '');
+        if (!productId) continue;
+        byProduct.set(productId, [
+            ...(_byProduct_get = byProduct.get(productId)) != null ? _byProduct_get : [],
+            _extends({}, (line == null ? void 0 : line['variantId']) ? {
+                variantId: String(line['variantId'])
+            } : {}, {
+                quantity: pick.quantity
+            })
+        ]);
+    }
+    let units = 0;
+    for (const [productId, lines] of byProduct){
+        const ref = hostRef.collection('products').doc(productId);
+        units += await firestore.runTransaction(async (transaction)=>{
+            const snapshot = await transaction.get(ref);
+            if (!snapshot.exists) return 0;
+            const product = CommerceModel.liftLegacyProduct(snapshot.data());
+            let variants = product.variants;
+            const rows = [];
+            for (const line of lines){
+                var _line_variantId;
+                var _product_variants_;
+                const variantId = (_line_variantId = line.variantId) != null ? _line_variantId : (_product_variants_ = product.variants[0]) == null ? void 0 : _product_variants_.id;
+                const variant = variants.find((candidate)=>candidate.id === variantId);
+                if (!variantId || !variant || variant.inventory == null) continue;
+                variants = CommerceModel.adjustVariantInventory({
+                    variants
+                }, variantId, line.quantity, locationId);
+                rows.push({
+                    variantId,
+                    quantity: line.quantity
+                });
+            }
+            if (!rows.length) return 0;
+            transaction.update(ref, _extends({
+                variants
+            }, CommerceModel.productStockFields(_extends({}, product, {
+                variants
+            })), {
+                updatedAtMs: now
+            }));
+            for (const row of rows){
+                transaction.create(hostRef.collection('inventoryAdjustments').doc(createResourceUid()), _extends({
+                    productId,
+                    variantId: row.variantId,
+                    delta: row.quantity,
+                    reason: 'refund',
+                    orderId
+                }, locationId ? {
+                    locationId
+                } : {}, {
+                    atMs: now
+                }));
+            }
+            return rows.reduce((sum, row)=>sum + row.quantity, 0);
+        });
+    }
+    return units;
+}
+export function createPosReturnHandler(deps = defaultPosReturnDeps) {
+    return async (req, res)=>{
+        try {
+            const outcome = await handlePosReturn(deps(), req);
+            return res.status(outcome.status).json(outcome.body);
+        } catch (error) {
+            console.error('[pos-return] failed', error);
+            return res.status(500).json({
+                error: 'The return could not be refunded'
+            });
+        }
+    };
+}
+export const posReturnHandler = createPosReturnHandler();
+
+//# sourceMappingURL=pos-return.js.map