@aglyn/plugins-commerce 1.0.0-beta.143

package/src/lib/server/refund.js

@@ -0,0 +1,607 @@
+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 * as Aglyn from "@aglyn/aglyn/server";
+import * as CommerceModel from "../model/index.js";
+import { firebaseAdmin, getOrgForHost } from "@aglyn/tenant-data-admin";
+import { resolveOrgPermissions } from "@aglyn/tenant-runtime/org-permissions";
+import { createHash } from "crypto";
+import { recordContactRefund } from "./contact-refund.js";
+import { flagOrderRestock } from "./restock-flag.js";
+// Leaf import, not the barrel, for the reason `contact-refund.ts` states about
+// `updateExisting`: the specs in this library mock `@aglyn/tenant-data-admin`
+// wholesale, and a permissive stub would turn a reversal that never happened
+// green.
+import { reverseEmailAttributedRevenue } from "@aglyn/tenant-data-admin/server/email-revenue-attribution";
+/**
+ * Retires the licence keys a refund withdrew (AGL-2454).
+ *
+ * Reads the order back so the decision is made from what actually SETTLED
+ * rather than from what this request asked for — a concurrent partial may have
+ * closed a line between the two — and retires only the keys of products the
+ * order no longer entitles at all. `refundedProductIds` is deliberately strict
+ * about that: a buyer who returned one of two copies still holds the product,
+ * so nothing is retired for them.
+ *
+ * `revokedAtMs` with `assignedAtMs` left standing is the retired state. Keeping
+ * `assignedAtMs` matters: `assignLicenseKeys` claims from
+ * `where('assignedAtMs','==',null)`, so clearing it would put the key straight
+ * back in front of the next buyer — the reissue this must not do.
+ *
+ * Swallows everything. The refund has already moved money.
+ */ async function retireLicenseKeys(hostRef, orderRef, orderId) {
+    try {
+        var _data;
+        const fresh = CommerceModel.liftLegacyOrder((_data = (await orderRef.get()).data()) != null ? _data : {});
+        const withdrawn = new Set(CommerceModel.refundedProductIds(fresh));
+        if (withdrawn.size === 0) return 0;
+        const assigned = await hostRef.collection('licenseKeys').where('orderId', '==', orderId).limit(500).get();
+        let retired = 0;
+        for (const keySnapshot of assigned.docs){
+            var _keySnapshot_get;
+            if (!withdrawn.has(String((_keySnapshot_get = keySnapshot.get('productId')) != null ? _keySnapshot_get : ''))) continue;
+            // Already retired by an earlier partial, or by the merchant's own Revoke
+            // button. Skipped so a second refund does not restamp the timestamp and
+            // make the retirement look newer than it is.
+            if (keySnapshot.get('revokedAtMs') != null) continue;
+            await keySnapshot.ref.set({
+                revokedAtMs: Date.now(),
+                revokedOrderId: orderId
+            }, {
+                merge: true
+            }).catch(()=>undefined);
+            retired++;
+        }
+        if (retired > 0) {
+            await orderRef.update({
+                timeline: firebaseAdmin.firestore.FieldValue.arrayUnion({
+                    atMs: Date.now(),
+                    event: 'license-retired',
+                    detail: `${retired} license key${retired === 1 ? '' : 's'} retired. ` + 'The buyer already holds the key string, so it is not returned ' + 'to the pool — reissuing it would give two people one secret.'
+                })
+            }).catch(()=>undefined);
+        }
+        return retired;
+    } catch (error) {
+        console.error('Licence key retirement failed', orderId, error);
+        return 0;
+    }
+}
+/**
+ * Order refunds (AGL-287): full or partial via Stripe, site-admin only
+ * (it moves money). Destination charges reverse the transfer and the
+ * platform fee proportionally. Full refunds transition the order to
+ * `refunded`; partial refunds accumulate `refundedCents` and stay in
+ * the current status.
+ *
+ * Two SEPARATE controls guard the money (AGL-1696), and conflating them is
+ * how the original went wrong:
+ *
+ *  - The idempotency key stops a DUPLICATE refund — one attempt sent twice
+ *    because the response was lost, the admin double-clicked, or a client
+ *    retried. It is minted per attempt by the console and deliberately not
+ *    derived from the order or the amount: two $10 refunds on a $50 order are
+ *    two real refunds, exactly as a cashier ringing the same coffee twice is a
+ *    real second sale.
+ *  - The cap stops an OVER-refund — several partials summing past what was
+ *    captured, including two admins refunding at once, where the two attempts
+ *    are genuinely distinct and no key can help. That needs the counter read
+ *    and written inside one transaction.
+ *
+ * The original had a cap that looked like both and was neither: it read
+ * `refundedCents` and wrote it back only AFTER the Stripe call, outside any
+ * transaction. A guard that reads state the guarded operation writes too late
+ * is not a guard — measured, two concurrent refunds each sent a full $50 to
+ * Stripe with no idempotency header on either.
+ */ export const refundHandler = async (req, res)=>{
+    var _req_headers_authorization, _req_body, _body_hostId, _body_orderId, _ref, _req_headers_idempotencykey;
+    if (req.method !== 'POST') {
+        return res.status(405).json({
+            error: 'Method not allowed'
+        });
+    }
+    if (!process.env.STRIPE_SECRET_KEY) {
+        return res.status(501).json({
+            error: 'Payments are not configured.'
+        });
+    }
+    const authorization = String((_req_headers_authorization = req.headers.authorization) != null ? _req_headers_authorization : '');
+    const idToken = authorization.startsWith('Bearer ') ? authorization.slice('Bearer '.length) : undefined;
+    if (!idToken) return res.status(401).json({
+        error: 'Unauthenticated'
+    });
+    const body = typeof req.body === 'string' ? JSON.parse(req.body) : (_req_body = req.body) != null ? _req_body : {};
+    const hostId = String((_body_hostId = body.hostId) != null ? _body_hostId : '');
+    const orderId = String((_body_orderId = body.orderId) != null ? _body_orderId : '');
+    const amountCents = body.amountCents == null ? null : Number(body.amountCents);
+    /**
+   * Lines the admin is refunding BY NAME (AGL-2454), and therefore the lines
+   * whose digital entitlements come back. Optional: an amount-only refund is
+   * still a legal refund and still revokes nothing per-line — see the guard
+   * below for why that is a decision rather than an oversight.
+   */ const requestedLineIds = Array.isArray(body.lineItemIds) ? [
+        ...new Set(body.lineItemIds.map((value)=>Math.round(Number(value))).filter((value)=>Number.isFinite(value) && value >= 0))
+    ].sort((a, b)=>a - b) : [];
+    // One refund attempt, minted by the console. Node lowercases incoming
+    // headers, but read both spellings — the plugin API request type makes no
+    // promise about casing.
+    const idempotencyKey = String((_ref = (_req_headers_idempotencykey = req.headers['idempotency-key']) != null ? _req_headers_idempotencykey : req.headers['Idempotency-Key']) != null ? _ref : '').trim().slice(0, 200);
+    if (!hostId || !orderId) {
+        return res.status(400).json({
+            error: 'Missing hostId or orderId'
+        });
+    }
+    let claim = null;
+    try {
+        var _hostSnapshot_get, _order_lineItems, _order_paymentIntentId;
+        const decoded = await firebaseAdmin.app().auth().verifyIdToken(idToken);
+        const firestore = firebaseAdmin.app().firestore();
+        const hostRef = firestore.collection('hosts').doc(hostId);
+        const hostSnapshot = await hostRef.get();
+        if (!hostSnapshot.exists) {
+            return res.status(404).json({
+                error: 'Unknown site'
+            });
+        }
+        // TWO CHECKS, and they answer different questions (AGL-2372).
+        //
+        // The first is the HOST-level fact the Firestore rules also enforce, and
+        // it stays: `memberRoles` is the projection the rules read, so dropping it
+        // here would let this route and the database disagree.
+        const memberRole = ((_hostSnapshot_get = hostSnapshot.get('memberRoles')) != null ? _hostSnapshot_get : {})[decoded.uid];
+        if (memberRole !== 'admin') {
+            return res.status(403).json({
+                error: 'Refunds require a site admin'
+            });
+        }
+        // The second is WHOSE admin, and it is the one this gate was missing.
+        //
+        // `memberRoles` is a per-host projection of `hostAccess`, and
+        // `/api/hosts/members` will grant a SITE COLLABORATOR `admin` on one site
+        // (`hostAccess: { [hostId]: 'admin' }`, `allHosts: false`). That writes the
+        // literal string `'admin'` into `memberRoles[uid]` — byte-identical to an
+        // org owner's. So the check above cannot tell a contractor invited to run
+        // one microsite from the person who owns the business, and refunding is
+        // money leaving that business.
+        //
+        // `orgWide` is the discriminator, and it needs no new role: it is
+        // `isOrgWideMember` (AGL-1026) — owner/admin of the org, an explicit
+        // `allHosts` member, or the legacy pre-`allHosts` shape — and it is false
+        // for every scoped collaborator. Same pairing `pos-order.ts` uses.
+        //
+        // BOTH halves are required. `hostRole` is re-tested rather than assumed
+        // from `memberRole`: an org-wide member can still be scoped down to
+        // `editor` on this host, and `resolveOrgPermissions` is the resolver that
+        // knows it. It fails CLOSED on a lookup error when a host is named
+        // (AGL-506), and `denied()` returns `orgWide: false` / `hostRole: null`,
+        // so an absent membership refuses rather than folding to permitted.
+        const membership = await resolveOrgPermissions(decoded.uid, {
+            hostId
+        });
+        if (!membership.orgWide || membership.hostRole !== 'admin') {
+            return res.status(403).json({
+                error: 'Refunds require an admin of the whole workspace'
+            });
+        }
+        const orderRef = hostRef.collection('orders').doc(orderId);
+        const orderSnapshot = await orderRef.get();
+        if (!orderSnapshot.exists) {
+            return res.status(404).json({
+                error: 'Unknown order'
+            });
+        }
+        const order = CommerceModel.liftLegacyOrder(orderSnapshot.data());
+        // Replay a settled attempt before anything else can reject it. This read
+        // is only a short-circuit, never the dedupe primitive — the atomic
+        // `create()` below is. It has to run ahead of the status guard because a
+        // retried FULL refund would otherwise be answered "orders in refunded
+        // cannot refund", which is the right money outcome reported as a failure,
+        // and an admin who reads it as a failure refunds again by hand.
+        const claimRef = idempotencyKey ? firestore.collection('apiIdempotency').doc(createHash('sha256')// Scoped by the order, so a client that reused one key across
+        // two orders cannot dedupe two legitimately distinct refunds.
+        // NOT by the amount: that would swallow a real second partial.
+        .update(`refund:${hostId}:${orderId}:${idempotencyKey}`).digest('hex')) : null;
+        if (claimRef) {
+            const prior = await claimRef.get();
+            const priorResponse = prior.get('response');
+            if (priorResponse) {
+                var _prior_get;
+                return res.status(Number((_prior_get = prior.get('responseStatus')) != null ? _prior_get : 200)).json(priorResponse);
+            }
+        }
+        if (!CommerceModel.canTransitionOrder(order.status, 'refunded')) {
+            return res.status(409).json({
+                error: `Orders in "${order.status}" cannot refund`
+            });
+        }
+        // A refund does not withdraw a dispute (AGL-1809). While a chargeback is
+        // formally open the bank has already pulled the disputed funds, Stripe's
+        // refund API refuses the charge (`charge_disputed`), and a refund that did
+        // go through would pay the shopper twice — the merchant loses the refund
+        // AND the dispute plus its fee. Refused HERE, before the claim and the
+        // reservation, so a refusal burns no idempotency key and strands nothing:
+        // no state has been written yet (AGL-1754's contract). An open INQUIRY
+        // (`warning_*`) deliberately passes — no funds have moved and Stripe names
+        // a full refund as the way to resolve one before it escalates — and the
+        // status guard above already turns away a LOST dispute, which parked the
+        // order in `refunded`. This reads the pre-transaction snapshot; a dispute
+        // webhook racing this exact request is caught by the `charge_disputed`
+        // mapping on the Stripe response below.
+        if (CommerceModel.orderDisputeBlocksRefund(order)) {
+            return res.status(409).json({
+                error: 'A chargeback is open on this order, so it was not refunded. ' + 'Refunding would not withdraw the dispute — the bank has already ' + 'taken the disputed amount, and a refund on top of it would pay ' + 'the shopper twice. Respond to the dispute or accept it in the ' + 'Stripe dashboard; refund any remainder once it settles.'
+            });
+        }
+        // WHAT THE NAMED LINES ARE WORTH, AND WHY THE AMOUNT MAY NOT BE LESS
+        // (AGL-2454).
+        //
+        // A refund carries an amount, not lines — that is the blocker this issue
+        // names, and `restock-flag.ts:48-55` already records it for stock. It
+        // cannot be solved by inference: deciding for the merchant which lines a
+        // bare figure covers would be a guess about their goods. It CAN be solved
+        // by asking, which is what naming lines does, and the amount is then
+        // derived from them rather than typed beside them.
+        //
+        // An explicit `amountCents` may still be LARGER (the admin is refunding the
+        // line plus its share of tax or shipping, which this items-only sum does
+        // not include). It may not be SMALLER: revoking a line the refund did not
+        // actually cover is the silent over-revocation this issue forbids in the
+        // same breath as silent under-revocation.
+        const orderLines = (_order_lineItems = order.lineItems) != null ? _order_lineItems : [];
+        const invalidLine = requestedLineIds.find((index)=>index >= orderLines.length);
+        if (invalidLine != null) {
+            return res.status(400).json({
+                error: `Line ${invalidLine} is not on this order`
+            });
+        }
+        // NET OF THE ORDER'S DISCOUNT, not the list price.
+        //
+        // This was the bare `unitAmountCents x quantity`, which is what the line
+        // was LISTED at rather than what the buyer paid for it. On a discounted
+        // order the two differ, and both directions of the error land on the
+        // merchant: a $10 coupon over two $50 lines means each line cost $45, so
+        // refunding one at $50 gave back $5 that was never taken, and the order
+        // then held less than its remaining line was worth — so the second line
+        // refund hit the cap below and was refused outright, leaving the merchant
+        // unable to finish a refund they had already half-issued.
+        //
+        // `orderLineRefundCents` apportions the discount across every line by list
+        // value and returns the named lines' share, so refunding all of them sums
+        // to exactly what was charged and no cent is stranded or invented.
+        const namedLinesCents = CommerceModel.orderLineRefundCents(order, requestedLineIds);
+        if (requestedLineIds.length > 0 && amountCents != null && Math.round(amountCents) < namedLinesCents) {
+            return res.status(400).json({
+                error: 'That amount is less than the lines you selected are worth. ' + 'Refund the full value of those lines, or refund an amount ' + 'without selecting lines.'
+            });
+        }
+        const paymentIntentId = (_order_paymentIntentId = order.paymentIntentId) != null ? _order_paymentIntentId : // Legacy rows stored the checkout session as the doc id; resolve
+        // the payment intent from Stripe.
+        await (async ()=>{
+            const response = await fetch(`https://api.stripe.com/v1/checkout/sessions/${orderId}`, {
+                headers: {
+                    Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}`
+                }
+            });
+            const session = await response.json();
+            return response.ok ? session == null ? void 0 : session.payment_intent : null;
+        })();
+        if (!paymentIntentId) {
+            return res.status(409).json({
+                error: 'No payment to refund'
+            });
+        }
+        // Point of no return: everything past here moves money. The claim is
+        // `create()` — Firestore rejects a create on an existing document, and
+        // that rejection IS the dedupe primitive. A read-then-write would race
+        // exactly the double-submit it exists to stop. Storage reuses the REST
+        // API's shape and its `orgId` field (AGL-618) rather than inventing a
+        // second replay store, so `eraseOrgIdempotencyKeys` (AGL-1448) already
+        // sweeps these on org erasure with no change there.
+        if (claimRef) {
+            const ownerOrg = await getOrgForHost(hostId);
+            try {
+                var _ref1;
+                var _ownerOrg_org;
+                await claimRef.create({
+                    orgId: String((_ref1 = ownerOrg == null ? void 0 : (_ownerOrg_org = ownerOrg.org) == null ? void 0 : _ownerOrg_org.id) != null ? _ref1 : '') || null,
+                    hostId,
+                    orderId,
+                    kind: 'commerce-refund',
+                    status: 'pending',
+                    createdAt: firebaseAdmin.firestore.FieldValue.serverTimestamp(),
+                    createdAtMs: Date.now(),
+                    // The second writer into `apiIdempotency` (AGL-1978). The shared
+                    // `claimAttempt` stamps this too; this local copy has to as well,
+                    // or refund claims are the one shape the TTL policy silently never
+                    // reaches — a policy that governs most of a collection reads, from
+                    // the outside, exactly like one that governs all of it.
+                    expiresAt: Aglyn.apiIdempotencyExpiry()
+                });
+            } catch (unused) {
+                const prior = await claimRef.get();
+                const priorResponse = prior.get('response');
+                if (priorResponse) {
+                    var _prior_get1;
+                    return res.status(Number((_prior_get1 = prior.get('responseStatus')) != null ? _prior_get1 : 200)).json(priorResponse);
+                }
+                // In flight, or stranded by a process that died mid-refund. Fail
+                // CLOSED: the alternative is sending the money a second time.
+                return res.status(409).json({
+                    error: 'This refund is already being processed'
+                });
+            }
+            claim = {
+                // The same digest goes to Stripe. That is the half that costs real
+                // money: it covers the window where our claim is written but the
+                // response never arrives, and makes Stripe replay its own refund
+                // instead of moving the funds again.
+                stripeKey: claimRef.id,
+                record: async (status, payload)=>{
+                    await claimRef.set({
+                        status: 'done',
+                        responseStatus: status,
+                        response: payload,
+                        settledAtMs: Date.now()
+                    }, {
+                        merge: true
+                    }).catch(()=>undefined);
+                },
+                release: async ()=>{
+                    await claimRef.delete().catch(()=>undefined);
+                }
+            };
+        }
+        // RESERVE. The cap is read and written in one transaction, so two
+        // concurrent refunds cannot both see the same `refundedCents` — which is
+        // the whole failure the old ordering had, since it wrote the counter only
+        // after Stripe had already been asked to move the money. Reserving BEFORE
+        // the call rather than after also fails in the safe direction: a lost
+        // response leaves the amount counted, so the retry refunds less, never
+        // more.
+        let refundCents = 0;
+        let totalCents = 0;
+        await firestore.runTransaction(async (transaction)=>{
+            var _data, _ref, _fresh_amountCents, _fresh_refundedCents;
+            var _fresh_totals;
+            const fresh = CommerceModel.liftLegacyOrder((_data = (await transaction.get(orderRef)).data()) != null ? _data : {});
+            totalCents = (_ref = (_fresh_totals = fresh.totals) == null ? void 0 : _fresh_totals.totalCents) != null ? _ref : Number((_fresh_amountCents = fresh.amountCents) != null ? _fresh_amountCents : 0);
+            const alreadyRefunded = Number((_fresh_refundedCents = fresh.refundedCents) != null ? _fresh_refundedCents : 0);
+            const remaining = totalCents - alreadyRefunded;
+            // Named lines with no amount refund exactly what those lines are worth;
+            // named lines WITH an amount use the amount (already guarded above as
+            // no smaller than the lines). Neither is the whole order, which is what
+            // `amountCents == null` alone still means.
+            const asked = amountCents != null ? Math.round(amountCents) : requestedLineIds.length > 0 ? namedLinesCents : remaining;
+            refundCents = Math.min(asked, remaining);
+            if (!(refundCents > 0)) {
+                refundCents = 0;
+                return;
+            }
+            transaction.set(orderRef, {
+                refundedCents: alreadyRefunded + refundCents
+            }, {
+                merge: true
+            });
+        });
+        if (!(refundCents > 0)) {
+            // Nothing moved, so the attempt key is released rather than burned.
+            await (claim == null ? void 0 : claim.release());
+            return res.status(400).json({
+                error: 'Nothing left to refund'
+            });
+        }
+        // The cap bit into the named lines (AGL-2454): earlier partials have left
+        // less on this order than the selected lines are worth. REFUSED rather
+        // than refunded-and-revoked, because revoking a line for less than its
+        // value is precisely the silent over-revocation this issue forbids. The
+        // reservation is given back — the same compensation a Stripe refusal does
+        // below, and for the same reason: nothing has left the account yet.
+        if (requestedLineIds.length > 0 && refundCents < namedLinesCents) {
+            await firestore.runTransaction(async (transaction)=>{
+                var _get;
+                const current = Number((_get = (await transaction.get(orderRef)).get('refundedCents')) != null ? _get : 0);
+                transaction.set(orderRef, {
+                    refundedCents: Math.max(0, current - refundCents)
+                }, {
+                    merge: true
+                });
+            }).catch(()=>undefined);
+            await (claim == null ? void 0 : claim.release());
+            return res.status(409).json({
+                error: `Only $${(refundCents / 100).toFixed(2)} is left to refund on this ` + `order, and the lines you selected are worth $${(namedLinesCents / 100).toFixed(2)}. Refund an amount without selecting lines instead.`
+            });
+        }
+        const params = new URLSearchParams({
+            payment_intent: String(paymentIntentId),
+            amount: String(refundCents),
+            reverse_transfer: 'true',
+            refund_application_fee: 'true'
+        });
+        const response = await fetch('https://api.stripe.com/v1/refunds', {
+            method: 'POST',
+            headers: _extends({
+                Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}`,
+                'Content-Type': 'application/x-www-form-urlencoded'
+            }, (claim == null ? void 0 : claim.stripeKey) ? {
+                'Idempotency-Key': claim.stripeKey
+            } : {}),
+            body: params.toString()
+        });
+        const refund = await response.json();
+        if (!response.ok) {
+            var _ref2, _ref3;
+            var _refund_error, _refund_error1;
+            console.error('Stripe refund error', refund == null ? void 0 : refund.error);
+            // Stripe said no, so we KNOW no money moved: give the reservation back
+            // and let the same attempt be tried again.
+            await firestore.runTransaction(async (transaction)=>{
+                var _get;
+                const current = Number((_get = (await transaction.get(orderRef)).get('refundedCents')) != null ? _get : 0);
+                transaction.set(orderRef, {
+                    refundedCents: Math.max(0, current - refundCents)
+                }, {
+                    merge: true
+                });
+            }).catch(()=>undefined);
+            await (claim == null ? void 0 : claim.release());
+            // Stripe refusing BECAUSE OF A DISPUTE is the guard above arriving by
+            // the other door — our order document simply didn't know yet (webhook
+            // lag, or an order from before disputes were subscribed at all). Same
+            // answer, same accuracy: a 409 naming the dispute, not a 502 reading
+            // "The charge you're attempting to refund has been charged back", which
+            // an admin has no reason to connect to the Refund button they pressed.
+            const stripeCode = String((_ref2 = refund == null ? void 0 : (_refund_error = refund.error) == null ? void 0 : _refund_error.code) != null ? _ref2 : '');
+            if (stripeCode === 'charge_disputed' || stripeCode === 'refund_disputed_payment') {
+                return res.status(409).json({
+                    error: 'Stripe refused this refund because the charge is disputed. ' + 'Respond to the dispute or accept it in the Stripe dashboard; ' + 'refund any remainder once it settles.'
+                });
+            }
+            return res.status(502).json({
+                error: (_ref3 = refund == null ? void 0 : (_refund_error1 = refund.error) == null ? void 0 : _refund_error1.message) != null ? _ref3 : 'Refund failed'
+            });
+        }
+        // SETTLE. Re-read inside the transaction: a concurrent partial may have
+        // reserved against the same order, and the timeline must be appended to
+        // whatever is there now rather than to the snapshot read at the top.
+        let refundedCents = 0;
+        let fullyRefunded = false;
+        let closedTheOrder = false;
+        await firestore.runTransaction(async (transaction)=>{
+            var _data, _fresh_refundedCents;
+            const fresh = CommerceModel.liftLegacyOrder((_data = (await transaction.get(orderRef)).data()) != null ? _data : {});
+            refundedCents = Number((_fresh_refundedCents = fresh.refundedCents) != null ? _fresh_refundedCents : 0);
+            fullyRefunded = refundedCents >= totalCents;
+            // Whether THIS settle moved the order into `refunded`, which is not the
+            // same question as whether the order is now fully refunded (AGL-1754).
+            // Two partials that between them close an order can both reserve before
+            // either settles, so both re-read the completed total and both compute
+            // `fullyRefunded`. Writing `status: 'refunded'` twice is harmless;
+            // incrementing a count twice is not. Reading the status inside the same
+            // transaction that writes it makes the flip observable exactly once.
+            closedTheOrder = fullyRefunded && fresh.status !== 'refunded';
+            transaction.set(orderRef, _extends({}, fullyRefunded ? {
+                status: 'refunded'
+            } : {}, requestedLineIds.length > 0 ? {
+                refundedLineItemIds: firebaseAdmin.firestore.FieldValue.arrayUnion(...requestedLineIds)
+            } : {}, {
+                timeline: CommerceModel.appendOrderEvent(fresh, 'refund', `$${(refundCents / 100).toFixed(2)} refunded` + (fullyRefunded ? ' (full)' : requestedLineIds.length > 0 ? ` — ${requestedLineIds.length} line${requestedLineIds.length === 1 ? '' : 's'} withdrawn` : ' — refunded by amount, no lines withdrawn'))
+            }), {
+                merge: true
+            });
+        });
+        const payload = {
+            refundedCents,
+            fullyRefunded
+        };
+        await (claim == null ? void 0 : claim.record(200, payload));
+        // LICENCE KEYS ARE RETIRED, NEVER RETURNED TO THE POOL (AGL-2454).
+        //
+        // `assignLicenseKeys` stamps `assignedAtMs`, `orderId` and `email` onto a
+        // pool document and nothing anywhere ever set them back — so a refunded
+        // order consumed the merchant's key forever, and a merchant who sold one
+        // key out of a hundred and refunded it had ninety-nine, permanently.
+        //
+        // Returning it to the pool is NOT the fix, and this is the decision the
+        // issue asked for: the key string was mailed in the receipt and cannot be
+        // invalidated by anything we own, so re-issuing it to the next paying
+        // customer would hand two people one working secret. That is worse than
+        // losing the key. A third state — retired: neither assigned to a live order
+        // nor available — is the honest record, and `revokedAtMs` already IS that
+        // state: the console's key dialog has written exactly this pair since it
+        // shipped, so this reuses the merchant's own vocabulary rather than
+        // inventing a second one.
+        //
+        // Best-effort and after the response is recorded, matching the contact and
+        // restock ledgers below: the money has moved and nothing here may fail a
+        // refund that already left the merchant's account.
+        await retireLicenseKeys(hostRef, orderRef, orderId);
+        // The customer's side of the ledger (AGL-1754). Everything above records
+        // the money on the ORDER; without this the buyer's `ltvCents` still counts
+        // a sale they returned, and only ever rises.
+        //
+        // Placed AFTER the attempt is recorded so a slow contacts write cannot
+        // strand the claim: a retry that arrives while this is in flight replays
+        // the recorded 200 instead of being turned away with "already being
+        // processed". Awaited rather than fired off with `void` — the handler is
+        // serverless, and work left running past the response is work the
+        // container may be frozen before it finishes. `recordContactRefund`
+        // swallows its own failures, so awaiting adds no way for this to fail a
+        // refund that has already left the merchant's account.
+        //
+        // Amount is THIS attempt's `refundCents`, already capped against what was
+        // left, so several partials sum to at most the order total — the same
+        // number the order's own `refundedCents` follows. The retried and racing
+        // cases need no key of their own: a keyed retry never reaches here (it
+        // replays at the claim), and a keyless one is a genuinely new refund that
+        // moved more money and should be counted.
+        await recordContactRefund({
+            hostId,
+            orderId,
+            email: order.customerEmail,
+            amountCents: refundCents,
+            closedTheOrder
+        });
+        /*
+     * The campaign's side of the same ledger.
+     *
+     * If a campaign was credited with this order, that credit is now partly
+     * or wholly wrong — a campaign cannot go on being paid for a sale the
+     * merchant reversed, and revenue attribution that only ever rises is the
+     * flattering half of a measurement. Recorded beside the gross rather than
+     * subtracted from it, for the reason `recordContactRefund` above records
+     * `refundedCents` beside `ltvCents`.
+     *
+     * Keyed by the ORDER and not by the buyer, so it needs no email and works
+     * for a guest checkout: the attribution record holds which campaign and
+     * which currency, and this reads them back. Same placement, same
+     * swallow-all contract and same awaited call as the two ledgers around
+     * it — nothing here may fail a refund that has already left the
+     * merchant's account.
+     */ await reverseEmailAttributedRevenue({
+            hostId,
+            orderId,
+            amountCents: refundCents,
+            closedTheOrder
+        });
+        // The shelf's side of the ledger (AGL-1797). The sale decremented variant
+        // inventory and nothing put it back, so a fully refunded order read one
+        // unit light forever. This FLAGS rather than releases — a refund with no
+        // return leaves the goods gone, and inventing stock the merchant does not
+        // have is worse than under-counting it — and the merchant answers from the
+        // stock adjustment they already have. Same placement and same swallow-all
+        // contract as the contact write above, for the same reason: the money has
+        // moved and the order records it, so nothing here may fail the refund.
+        await flagOrderRestock({
+            hostId,
+            orderId,
+            kind: 'refund',
+            closedTheOrder
+        });
+        return res.status(200).json(payload);
+    } catch (error) {
+        console.error(error);
+        // Deliberately NOT released, which is where this diverges from the POS
+        // sale path (AGL-1691). If the refund call threw we do not know whether
+        // Stripe moved the money, and the two failure directions are not
+        // symmetric: a stranded key costs a support ticket, a released one costs a
+        // second refund. The retry gets a 409 and a human reconciles.
+        return res.status(500).json({
+            error: 'Refund failed'
+        });
+    }
+};
+
+//# sourceMappingURL=refund.js.map