@aglyn/plugins-commerce 1.0.0-beta.201 → 1.0.0-beta.203

package/src/lib/server/billing-webhook.js

@@ -27,6 +27,8 @@ import { recordContactRefund } from "./contact-refund.js";
 import { reverseEmailAttributedRevenue } from "@aglyn/tenant-data-admin/server/email-revenue-attribution";
 import { paymentRiskEventFrom } from "@aglyn/aglyn/app-utils/payment-risk";
 import { recordPaymentRiskOnRecord } from "@aglyn/tenant-data-admin/server/payment-risk-record";
+import { isTransientStripeStatus, reverseDestinationTransfer } from "@aglyn/tenant-data-admin/server/stripe-transfer-reversal";
+import { applyExternalRefundToGiftCards, applyGiftCardRiskToOrder, notifyGiftCardHold } from "./gift-card-risk.js";
 import { mintDownloadToken, tokenSigningSecret } from "./download.js";
 import { alertLowStockCrossing } from "./low-stock.js";
 import { decrementVariantStock } from "./reserve-stock.js";
@@ -305,6 +307,66 @@ async function findOrderForDispute(paymentIntentId) {
         evidenceDueByMs: dueBy * 1000
     } : {});
 }
+/**
+ * Record, once, the part of `charge.amount_refunded` the order does not
+ * already account for (AGL-3363): the console's own refunds are reserved in
+ * `refundedCents` before Stripe is asked, and earlier Dashboard refunds are
+ * in `externalRefundedCents`. Returns the new amount and the order's lines,
+ * or null when there is nothing new — a console refund's own event, or a
+ * redelivery. One transaction, so two deliveries cannot both count it.
+ */ async function recordExternalRefund(orderRef, charge) {
+    var _ref;
+    const stripeRefundedCents = Math.max(0, Math.round(Number((_ref = charge == null ? void 0 : charge.amount_refunded) != null ? _ref : 0)));
+    if (!(stripeRefundedCents > 0)) return null;
+    return firebaseAdmin.app().firestore().runTransaction(async (transaction)=>{
+        var _fresh_data, _order_refundedCents, _data_externalRefundedCents, _order_lineItems;
+        const fresh = await transaction.get(orderRef);
+        if (!fresh.exists) return null;
+        const data = (_fresh_data = fresh.data()) != null ? _fresh_data : {};
+        const order = CommerceModel.liftLegacyOrder(data);
+        const consoleCents = Math.max(0, Number((_order_refundedCents = order.refundedCents) != null ? _order_refundedCents : 0));
+        const externalCents = Math.max(0, Number((_data_externalRefundedCents = data['externalRefundedCents']) != null ? _data_externalRefundedCents : 0));
+        const newCents = stripeRefundedCents - consoleCents - externalCents;
+        if (!(newCents > 0)) return null;
+        transaction.set(orderRef, {
+            externalRefundedCents: externalCents + newCents,
+            timeline: CommerceModel.appendOrderEvent(order, 'refund', `$${(newCents / 100).toFixed(2)} refunded outside the dashboard (in Stripe)`)
+        }, {
+            merge: true
+        });
+        return {
+            newCents,
+            fullyRefunded: (charge == null ? void 0 : charge.refunded) === true,
+            lines: ((_order_lineItems = order.lineItems) != null ? _order_lineItems : []).map((line)=>{
+                var _line_productId, _line_unitAmountCents, _line_quantity;
+                return {
+                    productId: String((_line_productId = line.productId) != null ? _line_productId : ''),
+                    totalCents: Math.round(Number((_line_unitAmountCents = line.unitAmountCents) != null ? _line_unitAmountCents : 0)) * Math.max(1, Math.round(Number((_line_quantity = line.quantity) != null ? _line_quantity : 1)))
+                };
+            })
+        };
+    });
+}
+/**
+ * Apply a gift-card risk action to the cards an order issued (AGL-3363). The
+ * order doc id is the Checkout Session id every issued card carries as its
+ * `orderId`. Never throws.
+ */ async function applyOrderGiftCardRisk(snapshot, action) {
+    try {
+        var _snapshot_ref_parent, _snapshot_ref;
+        const hostRef = (_snapshot_ref = snapshot.ref) == null ? void 0 : (_snapshot_ref_parent = _snapshot_ref.parent) == null ? void 0 : _snapshot_ref_parent.parent;
+        if (!hostRef) return 0;
+        return await applyGiftCardRiskToOrder({
+            firestore: firebaseAdmin.app().firestore(),
+            hostRef,
+            orderId: snapshot.id,
+            action
+        });
+    } catch (error) {
+        console.error('[gift-card-risk] skipped', snapshot.id, error);
+        return 0;
+    }
+}
 /**
  * `charge.dispute.created`: FLAG the order, reverse nothing (AGL-1787).
  *
@@ -575,9 +637,6 @@ async function findOrderForDispute(paymentIntentId) {
         link: `/${hostId}/products`
     });
 }
-/** Stripe failures a redelivery can actually fix. */ function isTransientStripeStatus(status) {
-    return status === 429 || status >= 500;
-}
 /** One authorized GET against the Stripe API, body parsed either way. */ async function stripeGet(url, stripeKey) {
     const response = await fetch(url, {
         headers: {
@@ -1369,8 +1428,7 @@ async function findOrderForDispute(paymentIntentId) {
  * notification is keyed on it, so a non-zero answer must mean "the write
  * happened HERE, and nobody has told the merchant yet".
  */ async function reverseSellerShare(orderRef, dispute) {
-    var _ref, _snapshot_data, _stored_reversedCents, _ref1, _ref2, _ref3, _ref4, _ref5, _ref6, _ref7, _ref8;
-    var _charge_body, _charge_body1, _transfer_body_reversals, _transfer_body, _transfer_body1, _transfer_body2;
+    var _ref, _snapshot_data, _stored_reversedCents, _ref1;
     const disputeId = String((_ref = dispute == null ? void 0 : dispute.id) != null ? _ref : '');
     if (!disputeId) return 0;
     const snapshot = await orderRef.get();
@@ -1427,103 +1485,42 @@ async function findOrderForDispute(paymentIntentId) {
             return true;
         });
     };
-    const chargeId = String((_ref1 = dispute == null ? void 0 : dispute.charge) != null ? _ref1 : '');
-    if (!chargeId) {
-        console.error('Dispute carries no charge; seller share not reversed', {
-            disputeId
-        });
-        await settle(0, null, 'Seller share not reversed — no charge on the dispute');
-        return 0;
-    }
-    const charge = await stripeGet(`https://api.stripe.com/v1/charges/${chargeId}`, stripeKey);
-    if (!charge.ok) {
-        var _charge_body2;
-        if (isTransientStripeStatus(charge.status)) {
-            throw new Error(`Stripe charge read failed (${charge.status}) for dispute ${disputeId}`);
-        }
-        console.error('Stripe refused the charge read; seller share not reversed', (_charge_body2 = charge.body) == null ? void 0 : _charge_body2.error);
-        await settle(0, null, 'Seller share not reversed — charge not found at Stripe');
-        return 0;
-    }
-    const transferId = String((_ref2 = (_charge_body = charge.body) == null ? void 0 : _charge_body.transfer) != null ? _ref2 : '');
-    const chargeAmountCents = Math.round(Number((_ref3 = (_charge_body1 = charge.body) == null ? void 0 : _charge_body1.amount) != null ? _ref3 : 0));
-    if (!transferId || !(chargeAmountCents > 0)) {
-        // An order from before destination charges, or a charge Stripe holds no
-        // transfer for. Logged, recorded, let go.
-        console.error('No transfer on the disputed charge; seller share not reversed', {
-            disputeId,
-            chargeId
-        });
-        await settle(0, null, 'Seller share not reversed — no transfer on the charge');
-        return 0;
-    }
-    const transfer = await stripeGet(`https://api.stripe.com/v1/transfers/${transferId}`, stripeKey);
-    if (!transfer.ok) {
-        var _transfer_body3;
-        if (isTransientStripeStatus(transfer.status)) {
-            throw new Error(`Stripe transfer read failed (${transfer.status}) for dispute ${disputeId}`);
+    // The Stripe half is the shared seam (AGL-3363): the booking deposit's lost
+    // dispute pulls back through the same function, so the two cannot drift.
+    const outcome = await reverseDestinationTransfer({
+        kind: 'dispute',
+        id: disputeId,
+        amountCents: principalCents,
+        chargeId: String((_ref1 = dispute == null ? void 0 : dispute.charge) != null ? _ref1 : ''),
+        metadata: {
+            orderId: orderRef.id
         }
-        console.error('Stripe refused the transfer read; seller share not reversed', (_transfer_body3 = transfer.body) == null ? void 0 : _transfer_body3.error);
-        await settle(0, null, 'Seller share not reversed — transfer not found at Stripe');
-        return 0;
-    }
-    // The crash window's backstop: the POST landed on a previous delivery and
-    // the record did not. Adopt what exists rather than creating a second one.
-    const existing = ((_ref4 = (_transfer_body = transfer.body) == null ? void 0 : (_transfer_body_reversals = _transfer_body.reversals) == null ? void 0 : _transfer_body_reversals.data) != null ? _ref4 : []).find((item)=>{
-        var _ref;
-        var _item_metadata;
-        return String((_ref = item == null ? void 0 : (_item_metadata = item.metadata) == null ? void 0 : _item_metadata.disputeId) != null ? _ref : '') === disputeId;
+    }, {
+        stripeKey
     });
-    if (existing) {
-        var _existing_amount, _existing_id;
-        const adoptedCents = Math.round(Number((_existing_amount = existing.amount) != null ? _existing_amount : 0));
-        // Announced on adoption too: the delivery that created this reversal died
-        // before recording it, so it died before notifying. The money left the
-        // connected account either way and the merchant has not been told yet.
-        const wrote = await settle(adoptedCents, String((_existing_id = existing.id) != null ? _existing_id : ''), `$${(adoptedCents / 100).toFixed(2)} seller share reversed for lost dispute`);
-        return wrote ? adoptedCents : 0;
-    }
-    const transferCents = Math.round(Number((_ref5 = (_transfer_body1 = transfer.body) == null ? void 0 : _transfer_body1.amount) != null ? _ref5 : 0));
-    const alreadyReversedCents = Math.round(Number((_ref6 = (_transfer_body2 = transfer.body) == null ? void 0 : _transfer_body2.amount_reversed) != null ? _ref6 : 0));
-    const remainingCents = Math.max(0, transferCents - alreadyReversedCents);
-    const shareCents = Math.min(chargeAmountCents > 0 ? Math.floor(principalCents * transferCents / chargeAmountCents) : 0, remainingCents);
-    if (!(shareCents > 0)) {
-        console.error('Transfer has nothing left to reverse; seller share not reversed', {
+    if (outcome.kind === 'skipped') return 0;
+    if (outcome.kind === 'not-reversed') {
+        console.error(outcome.reason === 'transfer-fully-reversed' ? 'Transfer has nothing left to reverse; seller share not reversed' : 'Seller share not reversed', {
             disputeId,
-            transferId,
-            transferCents,
-            alreadyReversedCents
+            reason: outcome.reason
         });
-        await settle(0, null, 'Seller share already reversed on the transfer — nothing left to pull back');
-        return 0;
-    }
-    const params = new URLSearchParams({
-        amount: String(shareCents),
-        'metadata[disputeId]': disputeId,
-        'metadata[orderId]': orderRef.id
-    });
-    const response = await fetch(`https://api.stripe.com/v1/transfers/${transferId}/reversals`, {
-        method: 'POST',
-        headers: {
-            Authorization: `Bearer ${stripeKey}`,
-            'Content-Type': 'application/x-www-form-urlencoded',
-            'Idempotency-Key': `dispute-reversal-${disputeId}`
-        },
-        body: params.toString()
-    });
-    const reversal = await response.json().catch(()=>null);
-    if (!response.ok) {
-        if (isTransientStripeStatus(response.status)) {
-            throw new Error(`Stripe transfer reversal failed (${response.status}) for dispute ${disputeId}`);
-        }
-        console.error('Stripe refused the transfer reversal', reversal == null ? void 0 : reversal.error);
-        await settle(0, null, 'Seller share not reversed — Stripe refused the reversal');
+        await settle(0, null, SELLER_SHARE_NOT_REVERSED_NOTE[outcome.reason]);
         return 0;
     }
-    const reversedTransferCents = Math.round(Number((_ref7 = reversal == null ? void 0 : reversal.amount) != null ? _ref7 : shareCents));
-    const wrote = await settle(reversedTransferCents, String((_ref8 = reversal == null ? void 0 : reversal.id) != null ? _ref8 : ''), `$${(reversedTransferCents / 100).toFixed(2)} seller share reversed for lost dispute`);
-    return wrote ? reversedTransferCents : 0;
+    // Announced on adoption too: the delivery that created an adopted reversal
+    // died before recording it, so it died before notifying. The money left the
+    // connected account either way and the merchant has not been told yet.
+    const wrote = await settle(outcome.cents, outcome.reversalId, `$${(outcome.cents / 100).toFixed(2)} seller share reversed for lost dispute`);
+    return wrote ? outcome.cents : 0;
 }
+/** The order timeline's words for each final reason nothing was pulled back. */ const SELLER_SHARE_NOT_REVERSED_NOTE = {
+    'no-charge-on-cause': 'Seller share not reversed — no charge on the dispute',
+    'charge-read-refused': 'Seller share not reversed — charge not found at Stripe',
+    'no-transfer-on-charge': 'Seller share not reversed — no transfer on the charge',
+    'transfer-read-refused': 'Seller share not reversed — transfer not found at Stripe',
+    'transfer-fully-reversed': 'Seller share already reversed on the transfer — nothing left to pull back',
+    'reversal-refused': 'Seller share not reversed — Stripe refused the reversal'
+};
 /**
  * Commerce sections of the platform Stripe webhook (AGL-418): relocated
  * verbatim from the console route — subscriptions sync, reservations,
@@ -3084,6 +3081,9 @@ async function findOrderForDispute(paymentIntentId) {
                         balanceCents: line.unitAmountCents,
                         recipientEmail: (_ref53 = object == null ? void 0 : (_object_customer_details12 = object.customer_details) == null ? void 0 : _object_customer_details12.email) != null ? _ref53 : null,
                         orderId: String(object.id),
+                        // Which line bought it, so a refund that withdraws that line
+                        // voids this card and no other (AGL-3363).
+                        productId: line.productId,
                         // What the console's Gift cards search asks (AGL-3321).
                         searchTokens: giftCardSearchTokens(code, (_ref54 = object == null ? void 0 : (_object_customer_details13 = object.customer_details) == null ? void 0 : _object_customer_details13.email) != null ? _ref54 : null),
                         createdAtMs: Date.now()
@@ -3887,6 +3887,48 @@ async function findOrderForDispute(paymentIntentId) {
             }
         }
     }
+    // A refund made OUTSIDE the console (AGL-3363) — in the Stripe Dashboard.
+    // `refund.ts` reserves `refundedCents` on the order before it asks Stripe,
+    // so by the time its own `charge.refunded` arrives the order already counts
+    // it; whatever Stripe has refunded beyond the order's count, and beyond the
+    // Dashboard refunds already recorded here, is new. The order's gift cards
+    // then follow the in-console rules (`applyExternalRefundToGiftCards`), and
+    // the refund is written on the order's timeline. Nothing else is moved: a
+    // Dashboard refund is staff's act, and they chose its transfer reversal.
+    if (type === 'charge.refunded') {
+        var _ref83, _ref84;
+        var _object_payment_intent, _snapshot_ref_parent_parent;
+        const paymentIntentId = typeof (object == null ? void 0 : object.payment_intent) === 'string' ? object.payment_intent : String((_ref83 = object == null ? void 0 : (_object_payment_intent = object.payment_intent) == null ? void 0 : _object_payment_intent.id) != null ? _ref83 : '');
+        const lookup = paymentIntentId ? await findOrderForDispute(paymentIntentId) : {
+            kind: 'not-ours'
+        };
+        if (lookup.kind !== 'order') return;
+        const snapshot = lookup.snapshot;
+        const hostId = String((_ref84 = (_snapshot_ref_parent_parent = snapshot.ref.parent.parent) == null ? void 0 : _snapshot_ref_parent_parent.id) != null ? _ref84 : '');
+        const external = await recordExternalRefund(snapshot.ref, object);
+        if (external && hostId && snapshot.ref.parent.parent) {
+            const outcome = await applyExternalRefundToGiftCards({
+                firestore: firebaseAdmin.app().firestore(),
+                hostRef: snapshot.ref.parent.parent,
+                orderId: snapshot.id,
+                lines: external.lines,
+                refundCents: external.newCents,
+                fullyRefunded: external.fullyRefunded
+            });
+            if (outcome.kind === 'frozen-for-review') {
+                await notifyGiftCardHold({
+                    hostId,
+                    orderLabel: `Order ${snapshot.id}`,
+                    cards: outcome.cards,
+                    reason: 'refund-review'
+                }, notifyHostManagers);
+            }
+        }
+        return {
+            claimed: true,
+            hostId
+        };
+    }
     // Fraud signals on a store's sale (AGL-3360): an issuer's early fraud
     // warning and a Radar review. The merchant decides what to do for their
     // own customer, so the signal lands on the ORDER — a timeline line and the
@@ -3898,14 +3940,14 @@ async function findOrderForDispute(paymentIntentId) {
     // merchant; both report the site so the seller's fraud ledger can name it.
     const risk = paymentRiskEventFrom(type, object);
     if (risk && risk.signal.kind !== 'dispute') {
-        var _ref83, _snapshot_data;
-        var _snapshot_ref_parent_parent;
+        var _ref85, _snapshot_data;
+        var _snapshot_ref_parent_parent1;
         const lookup = risk.paymentIntentId ? await findOrderForDispute(risk.paymentIntentId) : {
             kind: 'not-ours'
         };
         if (lookup.kind !== 'order') return;
         const snapshot = lookup.snapshot;
-        const hostId = String((_ref83 = (_snapshot_ref_parent_parent = snapshot.ref.parent.parent) == null ? void 0 : _snapshot_ref_parent_parent.id) != null ? _ref83 : '');
+        const hostId = String((_ref85 = (_snapshot_ref_parent_parent1 = snapshot.ref.parent.parent) == null ? void 0 : _snapshot_ref_parent_parent1.id) != null ? _ref85 : '');
         const order = CommerceModel.liftLegacyOrder((_snapshot_data = snapshot.data()) != null ? _snapshot_data : {});
         await recordPaymentRiskOnRecord({
             ref: snapshot.ref,
@@ -3921,6 +3963,18 @@ async function findOrderForDispute(paymentIntentId) {
             firestore: firebaseAdmin.app().firestore(),
             notify: notifyHostManagers
         });
+        // The cards this order bought are frozen until the merchant releases them
+        // (AGL-3363): a warning or review is the moment a stolen-card gift card
+        // is still unspent.
+        await notifyGiftCardHold({
+            hostId,
+            orderLabel: `Order ${CommerceModel.formatOrderNumber(order, snapshot.id)}`,
+            cards: await applyOrderGiftCardRisk(snapshot, {
+                kind: 'freeze',
+                reason: risk.signal.kind
+            }),
+            reason: risk.signal.kind
+        }, notifyHostManagers);
         return {
             claimed: true,
             hostId
@@ -3951,8 +4005,8 @@ async function findOrderForDispute(paymentIntentId) {
     // finds). AGL-1554 will add its own `closed` branch for the marketplace
     // side; the two coexist because each self-selects by finding its own record.
     if (type === 'charge.dispute.created' || type === 'charge.dispute.closed') {
-        var _dispute_payment_intent, _ref84;
-        var _snapshot_ref_parent_parent1;
+        var _dispute_payment_intent, _ref86;
+        var _snapshot_ref_parent_parent2;
         const dispute = object != null ? object : {};
         const paymentIntentId = String((_dispute_payment_intent = dispute.payment_intent) != null ? _dispute_payment_intent : '');
         const lookup = paymentIntentId ? await findOrderForDispute(paymentIntentId) : {
@@ -3977,10 +4031,20 @@ async function findOrderForDispute(paymentIntentId) {
         const claimed = lookup.kind === 'order' || lookup.kind === 'unresolved';
         const snapshot = lookup.kind === 'order' ? lookup.snapshot : null;
         if (snapshot) {
-            var _ref85;
-            var _snapshot_ref_parent_parent2;
-            const hostId = String((_ref85 = (_snapshot_ref_parent_parent2 = snapshot.ref.parent.parent) == null ? void 0 : _snapshot_ref_parent_parent2.id) != null ? _ref85 : '');
+            var _ref87;
+            var _snapshot_ref_parent_parent3;
+            const hostId = String((_ref87 = (_snapshot_ref_parent_parent3 = snapshot.ref.parent.parent) == null ? void 0 : _snapshot_ref_parent_parent3.id) != null ? _ref87 : '');
             if (type === 'charge.dispute.created') {
+                // A chargeback's gift cards are frozen while it is open (AGL-3363).
+                await notifyGiftCardHold({
+                    hostId,
+                    orderLabel: `Order ${snapshot.id}`,
+                    cards: await applyOrderGiftCardRisk(snapshot, {
+                        kind: 'freeze',
+                        reason: 'dispute'
+                    }),
+                    reason: 'dispute'
+                }, notifyHostManagers);
                 const { opened, record } = await recordDisputeOpened(snapshot, dispute);
                 if (opened && hostId) {
                     // Time-critical — Stripe's evidence window is days, not weeks — so
@@ -3996,7 +4060,17 @@ async function findOrderForDispute(paymentIntentId) {
                     });
                 }
             } else {
-                var _ref86;
+                var _ref88, _ref89;
+                // Lost: the money went back, so the cards it bought are voided. Won
+                // (or closed on a warning): the dispute's freeze lifts; a freeze a
+                // fraud warning or review put on stays for the merchant (AGL-3363).
+                await applyOrderGiftCardRisk(snapshot, String((_ref88 = dispute == null ? void 0 : dispute.status) != null ? _ref88 : '') === 'lost' ? {
+                    kind: 'void',
+                    reason: 'dispute-lost'
+                } : {
+                    kind: 'release',
+                    reason: 'dispute'
+                });
                 const settled = await recordDisputeClosed(snapshot, dispute);
                 if (settled.recorded && hostId) {
                     await notifyHostManagers(hostId, {
@@ -4054,7 +4128,7 @@ async function findOrderForDispute(paymentIntentId) {
                 // transiently-failed reversal gets its retry — and gated inside on
                 // the order's own `reversedTransferCents` marker, so it runs at most
                 // once per dispute however many times Stripe delivers.
-                if (String((_ref86 = dispute == null ? void 0 : dispute.status) != null ? _ref86 : '') === 'lost') {
+                if (String((_ref89 = dispute == null ? void 0 : dispute.status) != null ? _ref89 : '') === 'lost') {
                     const pulledBackCents = await reverseSellerShare(snapshot.ref, dispute);
                     // The merchant-experience half of the AGL-1794 decision, and not an
                     // optional extra: the reversal takes money out of the connected
@@ -4084,7 +4158,7 @@ async function findOrderForDispute(paymentIntentId) {
         return _extends({
             claimed
         }, snapshot ? {
-            hostId: String((_ref84 = (_snapshot_ref_parent_parent1 = snapshot.ref.parent.parent) == null ? void 0 : _snapshot_ref_parent_parent1.id) != null ? _ref84 : '')
+            hostId: String((_ref86 = (_snapshot_ref_parent_parent2 = snapshot.ref.parent.parent) == null ? void 0 : _snapshot_ref_parent_parent2.id) != null ? _ref86 : '')
         } : {});
     }
 };