@aglyn/plugins-commerce 1.0.0-beta.206 → 1.0.0-beta.209

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

@@ -15,8 +15,10 @@
  * limitations under the License.
  */ import { _ as _extends } from "@swc/helpers/_/_extends";
 import * as Aglyn from "@aglyn/aglyn/server";
-import { findUserByUidAcrossPools, firebaseAdmin, getOrgForHost, meterHostEmail, notifyHostManagers, notifyRiskEvent, notifyStaff, renderHostEmailWithTokens, clearConnectPayoutFailure, recordConnectPayoutFailure, syncConnectAccountStatus, updateExisting, hostSendingIdentity } from "@aglyn/tenant-data-admin";
+import { findUserByUidAcrossPools, firebaseAdmin, getOrgForHost, meterHostEmail, notifyHostManagers, notifyRiskEvent, raiseOperatorAlert, renderHostEmailWithTokens, clearConnectPayoutFailure, recordConnectPayoutFailure, syncConnectAccountStatus, updateExisting, hostSendingIdentity } from "@aglyn/tenant-data-admin";
 import { captureHostContact } from "@aglyn/tenant-runtime";
+import { formatOperatorAlertAmount } from "@aglyn/aglyn/app-utils/operator-alerts";
+import { COMMERCE_CHARGEBACK_UNROUTABLE, COMMERCE_FEE_REPRICE_REFUSED, COMMERCE_SELLER_SHARE_NOT_REVERSED, COMMERCE_TAX_NOT_REVERSED } from "../constants/operator-alerts.js";
 import { createHmac } from "crypto";
 import { isEmailConfigured, sendEmail } from "@aglyn/shared-util-email";
 import * as CommerceModel from "../model/index.js";
@@ -274,21 +276,37 @@ async function findOrderForDispute(paymentIntentId) {
  *
  * Staff, not the merchant: on the missing-index path there is no merchant to
  * tell — the whole point is that the order could not be found — and a missing
- * platform index is a platform fault affecting every host at once. `notifyStaff`
- * is the same channel the analytics and abuse routes use for exactly this
- * class, and it never throws.
+ * platform index is a platform fault affecting every host at once.
  *
- * `system.announcement` rather than a new type: the AGL-1088 rule is that
- * category is the prefix and `system` is the bucket nobody mutes to reduce
- * noise, which is the property an alert about unrouted money needs.
+ * As this plugin's own operator alert (AGL-3377), which reaches the operator's
+ * inbox and webhook as well as the console. A missing index is one alert for
+ * every chargeback it drops, not one per chargeback.
  */ async function reportUnresolvedDispute(reason, paymentIntentId, dispute) {
     var _dispute_amount;
-    const amount = `$${(((_dispute_amount = dispute.amount) != null ? _dispute_amount : 0) / 100).toFixed(2)}`;
-    await notifyStaff({
-        type: 'system.announcement',
-        title: 'Chargeback could not be routed to an order',
-        body: reason === 'missing-index' ? `A ${amount} chargeback (${paymentIntentId}) could not be looked ` + 'up: the collection-group index on orders.paymentIntentId is not ' + 'deployed, so EVERY commerce chargeback is currently being ignored ' + '— no flag, no seller-share reversal, no merchant notification. ' + 'Deploy cloud/firebase-firestore.indexes.json.' : `A ${amount} chargeback (${paymentIntentId}) matched more than one ` + 'order, so none was reversed. The dispute is durable in Stripe and ' + 'needs reconciling by hand.',
-        link: '/admin'
+    const amount = formatOperatorAlertAmount((_dispute_amount = dispute.amount) != null ? _dispute_amount : 0);
+    await raiseOperatorAlert(COMMERCE_CHARGEBACK_UNROUTABLE, {
+        dedupeKey: reason === 'missing-index' ? 'missing-index' : paymentIntentId,
+        url: '/admin',
+        context: {
+            amount,
+            detail: reason === 'missing-index' ? `A ${amount} chargeback (${paymentIntentId}) could not be looked ` + 'up: the collection-group index on orders.paymentIntentId is not ' + 'deployed, so EVERY commerce chargeback is currently being ignored ' + '— no flag, no seller-share reversal, no merchant notification. ' + 'Deploy cloud/firebase-firestore.indexes.json.' : `A ${amount} chargeback (${paymentIntentId}) matched more than one ` + 'order, so none was reversed. The dispute is durable in Stripe and ' + 'needs reconciling by hand.'
+        }
+    });
+}
+/**
+ * Tells the operator that a subscription cycle's sales tax stayed with the
+ * merchant (AGL-3377): the platform files and remits it, so every one of
+ * these is tax it may owe and does not hold. Once per invoice and outcome, so
+ * Stripe's redeliveries of the same invoice say it once.
+ */ async function reportTaxNotReversed(input) {
+    await raiseOperatorAlert(COMMERCE_TAX_NOT_REVERSED, {
+        dedupeKey: `${input.invoiceId}:${input.status}`,
+        context: {
+            invoiceId: input.invoiceId,
+            hostId: input.hostId,
+            amount: input.taxCents === undefined ? 'An unknown amount' : formatOperatorAlertAmount(input.taxCents),
+            reason: input.reason
+        }
     });
 }
 /** The dispute record this event describes, before any outcome is known. */ function disputeFromEvent(dispute) {
@@ -713,10 +731,21 @@ async function findOrderForDispute(paymentIntentId) {
         }).toString()
     }).catch(()=>null);
     if (!response || !response.ok) {
+        var _ref, _ref1;
+        var _subscriptionRef_parent_parent, _refusal_error;
         if (!response || isTransientStripeStatus(response.status)) {
             throw new Error(`Stripe refused to re-price subscription ${subscriptionId} ` + `(${response ? response.status : 'network'})`);
         }
-        console.error(`Stripe refused the fee re-price for ${subscriptionId} (AGL-2289)`, await response.json().catch(()=>null));
+        const refusal = await response.json().catch(()=>null);
+        console.error(`Stripe refused the fee re-price for ${subscriptionId} (AGL-2289)`, refusal);
+        await raiseOperatorAlert(COMMERCE_FEE_REPRICE_REFUSED, {
+            dedupeKey: `${subscriptionId}:${desiredFeePct}`,
+            context: {
+                subject: `subscription ${subscriptionId}`,
+                hostId: (_ref = (_subscriptionRef_parent_parent = subscriptionRef.parent.parent) == null ? void 0 : _subscriptionRef_parent_parent.id) != null ? _ref : '',
+                reason: `Stripe refused to set the fee to ${desiredFeePct}% (${(_ref1 = refusal == null ? void 0 : (_refusal_error = refusal.error) == null ? void 0 : _refusal_error.message) != null ? _ref1 : `HTTP ${response.status}`})`
+            }
+        });
         return;
     }
     await subscriptionRef.set({
@@ -725,6 +754,20 @@ async function findOrderForDispute(paymentIntentId) {
         merge: true
     }).catch(()=>undefined);
 }
+/**
+ * Tells the operator a subscription cycle kept a fee charged on the wrong
+ * base (AGL-3377): the merchant paid more than the plan sets. Once per
+ * invoice.
+ */ async function reportFeeNotCorrected(hostId, invoiceId, reason) {
+    await raiseOperatorAlert(COMMERCE_FEE_REPRICE_REFUSED, {
+        dedupeKey: invoiceId,
+        context: {
+            subject: `invoice ${invoiceId}`,
+            hostId,
+            reason
+        }
+    });
+}
 /**
  * The charge a paid invoice settled against, on whichever spelling this
  * endpoint's API version uses (AGL-2317).
@@ -848,6 +891,7 @@ async function findOrderForDispute(paymentIntentId) {
             hostId,
             invoiceId
         });
+        await reportFeeNotCorrected(hostId, invoiceId, 'STRIPE_SECRET_KEY is not set on this deployment');
         return chargedCents;
     }
     const chargeId = await resolveInvoiceChargeId(invoice, stripeKey);
@@ -856,6 +900,7 @@ async function findOrderForDispute(paymentIntentId) {
             hostId,
             invoiceId
         });
+        await reportFeeNotCorrected(hostId, invoiceId, 'the invoice names no charge');
         return chargedCents;
     }
     const fees = await stripeGet(`https://api.stripe.com/v1/application_fees?limit=1&charge=${encodeURIComponent(chargeId)}`, stripeKey);
@@ -870,6 +915,7 @@ async function findOrderForDispute(paymentIntentId) {
             chargeId,
             status: fees.status
         });
+        await reportFeeNotCorrected(hostId, invoiceId, `no application fee was found on charge ${chargeId}`);
         return chargedCents;
     }
     const feeAmount = Math.max(0, Math.round(Number((_fee_amount = fee.amount) != null ? _fee_amount : 0)));
@@ -890,6 +936,8 @@ async function findOrderForDispute(paymentIntentId) {
         }).toString()
     }).catch(()=>null);
     if (!response || !response.ok) {
+        var _ref1;
+        var _refusal_error;
         if (!response || isTransientStripeStatus(response.status)) {
             // Let Stripe redeliver — the ledger write is keyed on the invoice id, so
             // a retry re-runs this and nothing else (the AGL-1743 discipline).
@@ -897,7 +945,9 @@ async function findOrderForDispute(paymentIntentId) {
         }
         // Definitive: no redelivery fixes it, and throwing would have Stripe retry
         // the whole invoice forever. Record what was actually taken.
-        console.error(`Stripe refused the items-only fee correction for ${invoiceId} (AGL-2317)`, await response.json().catch(()=>null));
+        const refusal = await response.json().catch(()=>null);
+        console.error(`Stripe refused the items-only fee correction for ${invoiceId} (AGL-2317)`, refusal);
+        await reportFeeNotCorrected(hostId, invoiceId, `Stripe refused to refund ${formatOperatorAlertAmount(refundCents)} of the fee (${(_ref1 = refusal == null ? void 0 : (_refusal_error = refusal.error) == null ? void 0 : _refusal_error.message) != null ? _ref1 : `HTTP ${response.status}`})`);
         return chargedCents;
     }
     return desiredCents;
@@ -1102,11 +1152,12 @@ async function findOrderForDispute(paymentIntentId) {
             status: 'unreadable',
             reason: decision.reason
         });
-        void notifyStaff({
-            type: 'system.announcement',
-            title: 'A subscription invoice stated no readable tax',
-            body: `Invoice ${invoiceId} enables automatic tax but names no tax field, so ` + `no reversal was made. Aglyn may owe tax it did not pull back. ` + `${decision.reason}`
-        }).catch(()=>undefined);
+        await reportTaxNotReversed({
+            hostId,
+            invoiceId,
+            status: 'unreadable',
+            reason: `the invoice enables automatic tax but states no readable tax field (${decision.reason})`
+        });
         return;
     }
     const taxCents = decision.taxCents;
@@ -1116,6 +1167,13 @@ async function findOrderForDispute(paymentIntentId) {
             hostId,
             invoiceId
         });
+        await reportTaxNotReversed({
+            hostId,
+            invoiceId,
+            taxCents,
+            status: 'no-key',
+            reason: 'STRIPE_SECRET_KEY is not set on this deployment'
+        });
         return;
     }
     // GUARD 1. Every ordinary redelivery stops here, before any Stripe call, and
@@ -1168,6 +1226,13 @@ async function findOrderForDispute(paymentIntentId) {
                 status: 'charge-unreadable',
                 taxCents
             });
+            await reportTaxNotReversed({
+                hostId,
+                invoiceId,
+                taxCents,
+                status: 'charge-unreadable',
+                reason: `Stripe refused to read charge ${chargeId}`
+            });
             return;
         }
         const transferId = String((_ref = (_charge_body = charge.body) == null ? void 0 : _charge_body.transfer) != null ? _ref : '');
@@ -1197,6 +1262,13 @@ async function findOrderForDispute(paymentIntentId) {
                 status: 'transfer-unreadable',
                 taxCents
             });
+            await reportTaxNotReversed({
+                hostId,
+                invoiceId,
+                taxCents,
+                status: 'transfer-unreadable',
+                reason: `Stripe refused to read transfer ${transferId}`
+            });
             return;
         }
         // GUARD 2 — the crash window, and LOAD-BEARING now that the idempotency key
@@ -1258,6 +1330,13 @@ async function findOrderForDispute(paymentIntentId) {
                 transferId,
                 owedCents: taxCents
             });
+            await reportTaxNotReversed({
+                hostId,
+                invoiceId,
+                taxCents,
+                status: 'nothing-left',
+                reason: `transfer ${transferId} had nothing left to reverse, so the tax must be reconciled by hand`
+            });
             return;
         }
         const response = await fetch(`https://api.stripe.com/v1/transfers/${encodeURIComponent(transferId)}/reversals`, {
@@ -1313,11 +1392,13 @@ async function findOrderForDispute(paymentIntentId) {
                     status: 'refused'
                 }, failureFields));
             }
-            void notifyStaff({
-                type: 'system.announcement',
-                title: 'A subscription sales-tax reversal failed',
-                body: `$${(taxCents / 100).toFixed(2)} of sales tax on invoice ${invoiceId} ` + `is still with the merchant and Aglyn owes it. ` + (insufficient ? 'The connected account had insufficient balance; this will retry.' : `Stripe refused: ${String((_ref9 = body == null ? void 0 : (_body_error2 = body.error) == null ? void 0 : _body_error2.message) != null ? _ref9 : 'no reason given')}`)
-            }).catch(()=>undefined);
+            await reportTaxNotReversed({
+                hostId,
+                invoiceId,
+                taxCents,
+                status: insufficient ? 'insufficient' : 'refused',
+                reason: insufficient ? 'the connected account had insufficient balance; it will retry on the next delivery' : `Stripe refused the reversal: ${String((_ref9 = body == null ? void 0 : (_body_error2 = body.error) == null ? void 0 : _body_error2.message) != null ? _ref9 : 'no reason given')}`
+            });
             return;
         }
         const reversedCents = Math.max(0, Math.round(Number((_ref4 = body == null ? void 0 : body.amount) != null ? _ref4 : reverseCents)));
@@ -1449,6 +1530,7 @@ async function findOrderForDispute(paymentIntentId) {
     const stripeKey = process.env.STRIPE_SECRET_KEY;
     if (!stripeKey) {
         console.error('Transfer reversal skipped: STRIPE_SECRET_KEY is not set (AGL-1794)');
+        await reportSellerShareNotReversed(orderRef, disputeId, principalCents, 'STRIPE_SECRET_KEY is not set on this deployment');
         return 0;
     }
     /**
@@ -1505,6 +1587,10 @@ async function findOrderForDispute(paymentIntentId) {
             reason: outcome.reason
         });
         await settle(0, null, SELLER_SHARE_NOT_REVERSED_NOTE[outcome.reason]);
+        // Already reversed on the transfer is money back, not money lost.
+        if (outcome.reason !== 'transfer-fully-reversed') {
+            await reportSellerShareNotReversed(orderRef, disputeId, principalCents, SELLER_SHARE_NOT_REVERSED_NOTE[outcome.reason]);
+        }
         return 0;
     }
     // Announced on adoption too: the delivery that created an adopted reversal
@@ -1513,6 +1599,23 @@ async function findOrderForDispute(paymentIntentId) {
     const wrote = await settle(outcome.cents, outcome.reversalId, `$${(outcome.cents / 100).toFixed(2)} seller share reversed for lost dispute`);
     return wrote ? outcome.cents : 0;
 }
+/**
+ * Tells the operator the platform is out a lost dispute's principal because
+ * the merchant's share could not be pulled back (AGL-3377). Once per dispute.
+ */ async function reportSellerShareNotReversed(orderRef, disputeId, principalCents, reason) {
+    var _ref;
+    var _orderRef_parent_parent;
+    await raiseOperatorAlert(COMMERCE_SELLER_SHARE_NOT_REVERSED, {
+        dedupeKey: disputeId,
+        context: {
+            disputeId,
+            orderId: orderRef.id,
+            hostId: (_ref = (_orderRef_parent_parent = orderRef.parent.parent) == null ? void 0 : _orderRef_parent_parent.id) != null ? _ref : '',
+            amount: formatOperatorAlertAmount(principalCents),
+            reason
+        }
+    });
+}
 /** 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',