@aglyn/plugins-commerce 1.0.0-beta.205 → 1.0.0-beta.207

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/plugins-commerce",
-  "version": "1.0.0-beta.205",
+  "version": "1.0.0-beta.207",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -25,18 +25,18 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/aglyn": "1.0.0-beta.205",
-    "@aglyn/shared-data-mdi": "1.0.0-beta.205",
-    "@aglyn/shared-ui-jsx": "1.0.0-beta.205",
-    "@aglyn/shared-ui-next": "1.0.0-beta.205",
-    "@aglyn/shared-ui-snackstack": "1.0.0-beta.205",
-    "@aglyn/shared-util-email": "1.0.0-beta.205",
-    "@aglyn/shared-util-http": "1.0.0-beta.205",
-    "@aglyn/shared-util-timestamp": "1.0.0-beta.205",
-    "@aglyn/shared-util-tools": "1.0.0-beta.205",
-    "@aglyn/tenant-data-admin": "1.0.0-beta.205",
-    "@aglyn/tenant-feature-instance": "1.0.0-beta.205",
-    "@aglyn/tenant-runtime": "1.0.0-beta.205",
+    "@aglyn/aglyn": "1.0.0-beta.207",
+    "@aglyn/shared-data-mdi": "1.0.0-beta.207",
+    "@aglyn/shared-ui-jsx": "1.0.0-beta.207",
+    "@aglyn/shared-ui-next": "1.0.0-beta.207",
+    "@aglyn/shared-ui-snackstack": "1.0.0-beta.207",
+    "@aglyn/shared-util-email": "1.0.0-beta.207",
+    "@aglyn/shared-util-http": "1.0.0-beta.207",
+    "@aglyn/shared-util-timestamp": "1.0.0-beta.207",
+    "@aglyn/shared-util-tools": "1.0.0-beta.207",
+    "@aglyn/tenant-data-admin": "1.0.0-beta.207",
+    "@aglyn/tenant-feature-instance": "1.0.0-beta.207",
+    "@aglyn/tenant-runtime": "1.0.0-beta.207",
     "@stripe/react-stripe-js": "^3.10.0",
     "@stripe/stripe-js": "^5.10.0",
     "@swc/helpers": "0.5.23",

package/src/lib/constants/operator-alerts.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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 type { OperatorAlertDefinition } from '@aglyn/aglyn/app-utils/operator-alerts';
+export declare const COMMERCE_CHARGEBACK_UNROUTABLE: OperatorAlertDefinition;
+export declare const COMMERCE_TAX_NOT_REVERSED: OperatorAlertDefinition;
+export declare const COMMERCE_SELLER_SHARE_NOT_REVERSED: OperatorAlertDefinition;
+export declare const COMMERCE_FEE_REPRICE_REFUSED: OperatorAlertDefinition;
+export declare const COMMERCE_OPERATOR_ALERTS: readonly OperatorAlertDefinition[];

package/src/lib/constants/operator-alerts.js

@@ -0,0 +1,85 @@
+/**
+ * @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 { BUNDLE_ID } from "./bundle-common.js";
+/**
+ * The storefront's operator alerts (AGL-3377): the money faults only this
+ * plugin can see, declared in the registry's shape and registered from
+ * `declarations.server`, so core lists none of them and an install without
+ * commerce shows none of them on Staff → Operator alerts.
+ *
+ * Each is raised through `raiseOperatorAlert` with its definition, which
+ * also registers it in a process whose declarations have not loaded yet.
+ */ const DAY = 24 * 60;
+export const COMMERCE_CHARGEBACK_UNROUTABLE = {
+    type: 'commerce.chargebackUnroutable',
+    pluginId: BUNDLE_ID,
+    label: 'Storefront chargeback could not be routed',
+    description: 'A storefront chargeback matched no order, or more than one, so no order was flagged, no seller share reversed and no merchant told. A missing index means every storefront chargeback is being ignored.',
+    tier: 'must',
+    category: 'payments',
+    title: 'A {{amount}} chargeback could not be routed to an order',
+    body: '{{detail}}',
+    delivery: 'immediate',
+    dedupeWindowMinutes: DAY,
+    defaultEnabled: true
+};
+export const COMMERCE_TAX_NOT_REVERSED = {
+    type: 'commerce.taxNotReversed',
+    pluginId: BUNDLE_ID,
+    label: 'Subscription sales tax not reversed',
+    description: 'Sales tax collected on a storefront subscription stayed with the merchant instead of coming back to the platform, which files and remits it. The platform may owe tax it does not hold.',
+    tier: 'must',
+    category: 'payments',
+    title: 'Sales tax not reversed on invoice {{invoiceId}}',
+    body: '{{amount}} of sales tax on invoice {{invoiceId}} (site {{hostId}}) was not pulled back from the merchant: {{reason}}.',
+    delivery: 'immediate',
+    dedupeWindowMinutes: 7 * DAY,
+    defaultEnabled: true
+};
+export const COMMERCE_SELLER_SHARE_NOT_REVERSED = {
+    type: 'commerce.sellerShareNotReversed',
+    pluginId: BUNDLE_ID,
+    label: 'Seller share not reversed on a lost dispute',
+    description: 'A storefront dispute was lost and the merchant’s share could not be pulled back, so the platform is out the principal. Recover it by hand in Stripe.',
+    tier: 'must',
+    category: 'payments',
+    title: 'Seller share not reversed on dispute {{disputeId}}',
+    body: 'The lost dispute {{disputeId}} on order {{orderId}} (site {{hostId}}) cost {{amount}}, and the merchant’s share was not reversed: {{reason}}.',
+    delivery: 'immediate',
+    dedupeWindowMinutes: 30 * DAY,
+    defaultEnabled: true
+};
+export const COMMERCE_FEE_REPRICE_REFUSED = {
+    type: 'commerce.feeRepriceRefused',
+    pluginId: BUNDLE_ID,
+    label: 'Platform fee correction refused',
+    description: 'Stripe refused to change a storefront subscription’s platform fee, or to refund the part of a fee charged on the wrong base. The merchant is being charged a fee the plan does not set.',
+    tier: 'must',
+    category: 'payments',
+    title: 'Platform fee not corrected on {{subject}}',
+    body: 'The platform fee on {{subject}} (site {{hostId}}) could not be corrected: {{reason}}.',
+    delivery: 'immediate',
+    dedupeWindowMinutes: 7 * DAY,
+    defaultEnabled: true
+};
+export const COMMERCE_OPERATOR_ALERTS = [
+    COMMERCE_CHARGEBACK_UNROUTABLE,
+    COMMERCE_TAX_NOT_REVERSED,
+    COMMERCE_SELLER_SHARE_NOT_REVERSED,
+    COMMERCE_FEE_REPRICE_REFUSED
+];
+
+//# sourceMappingURL=operator-alerts.js.map

package/src/lib/constants/operator-alerts.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/constants/operator-alerts.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { OperatorAlertDefinition } from '@aglyn/aglyn/app-utils/operator-alerts'\nimport { BUNDLE_ID } from './bundle-common'\n\n/**\n * The storefront's operator alerts (AGL-3377): the money faults only this\n * plugin can see, declared in the registry's shape and registered from\n * `declarations.server`, so core lists none of them and an install without\n * commerce shows none of them on Staff → Operator alerts.\n *\n * Each is raised through `raiseOperatorAlert` with its definition, which\n * also registers it in a process whose declarations have not loaded yet.\n */\nconst DAY = 24 * 60\n\nexport const COMMERCE_CHARGEBACK_UNROUTABLE: OperatorAlertDefinition = {\n  type: 'commerce.chargebackUnroutable',\n  pluginId: BUNDLE_ID,\n  label: 'Storefront chargeback could not be routed',\n  description:\n    'A storefront chargeback matched no order, or more than one, so no order was flagged, no seller share reversed and no merchant told. A missing index means every storefront chargeback is being ignored.',\n  tier: 'must',\n  category: 'payments',\n  title: 'A {{amount}} chargeback could not be routed to an order',\n  body: '{{detail}}',\n  delivery: 'immediate',\n  dedupeWindowMinutes: DAY,\n  defaultEnabled: true,\n}\n\nexport const COMMERCE_TAX_NOT_REVERSED: OperatorAlertDefinition = {\n  type: 'commerce.taxNotReversed',\n  pluginId: BUNDLE_ID,\n  label: 'Subscription sales tax not reversed',\n  description:\n    'Sales tax collected on a storefront subscription stayed with the merchant instead of coming back to the platform, which files and remits it. The platform may owe tax it does not hold.',\n  tier: 'must',\n  category: 'payments',\n  title: 'Sales tax not reversed on invoice {{invoiceId}}',\n  body:\n    '{{amount}} of sales tax on invoice {{invoiceId}} (site {{hostId}}) was not pulled back from the merchant: {{reason}}.',\n  delivery: 'immediate',\n  dedupeWindowMinutes: 7 * DAY,\n  defaultEnabled: true,\n}\n\nexport const COMMERCE_SELLER_SHARE_NOT_REVERSED: OperatorAlertDefinition = {\n  type: 'commerce.sellerShareNotReversed',\n  pluginId: BUNDLE_ID,\n  label: 'Seller share not reversed on a lost dispute',\n  description:\n    'A storefront dispute was lost and the merchant’s share could not be pulled back, so the platform is out the principal. Recover it by hand in Stripe.',\n  tier: 'must',\n  category: 'payments',\n  title: 'Seller share not reversed on dispute {{disputeId}}',\n  body:\n    'The lost dispute {{disputeId}} on order {{orderId}} (site {{hostId}}) cost {{amount}}, and the merchant’s share was not reversed: {{reason}}.',\n  delivery: 'immediate',\n  dedupeWindowMinutes: 30 * DAY,\n  defaultEnabled: true,\n}\n\nexport const COMMERCE_FEE_REPRICE_REFUSED: OperatorAlertDefinition = {\n  type: 'commerce.feeRepriceRefused',\n  pluginId: BUNDLE_ID,\n  label: 'Platform fee correction refused',\n  description:\n    'Stripe refused to change a storefront subscription’s platform fee, or to refund the part of a fee charged on the wrong base. The merchant is being charged a fee the plan does not set.',\n  tier: 'must',\n  category: 'payments',\n  title: 'Platform fee not corrected on {{subject}}',\n  body: 'The platform fee on {{subject}} (site {{hostId}}) could not be corrected: {{reason}}.',\n  delivery: 'immediate',\n  dedupeWindowMinutes: 7 * DAY,\n  defaultEnabled: true,\n}\n\nexport const COMMERCE_OPERATOR_ALERTS: readonly OperatorAlertDefinition[] = [\n  COMMERCE_CHARGEBACK_UNROUTABLE,\n  COMMERCE_TAX_NOT_REVERSED,\n  COMMERCE_SELLER_SHARE_NOT_REVERSED,\n  COMMERCE_FEE_REPRICE_REFUSED,\n]\n"],"names":["BUNDLE_ID","DAY","COMMERCE_CHARGEBACK_UNROUTABLE","type","pluginId","label","description","tier","category","title","body","delivery","dedupeWindowMinutes","defaultEnabled","COMMERCE_TAX_NOT_REVERSED","COMMERCE_SELLER_SHARE_NOT_REVERSED","COMMERCE_FEE_REPRICE_REFUSED","COMMERCE_OPERATOR_ALERTS"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAGD,SAASA,SAAS,QAAQ,qBAAiB;AAE3C;;;;;;;;CAQC,GACD,MAAMC,MAAM,KAAK;AAEjB,OAAO,MAAMC,iCAA0D;IACrEC,MAAM;IACNC,UAAUJ;IACVK,OAAO;IACPC,aACE;IACFC,MAAM;IACNC,UAAU;IACVC,OAAO;IACPC,MAAM;IACNC,UAAU;IACVC,qBAAqBX;IACrBY,gBAAgB;AAClB,EAAC;AAED,OAAO,MAAMC,4BAAqD;IAChEX,MAAM;IACNC,UAAUJ;IACVK,OAAO;IACPC,aACE;IACFC,MAAM;IACNC,UAAU;IACVC,OAAO;IACPC,MACE;IACFC,UAAU;IACVC,qBAAqB,IAAIX;IACzBY,gBAAgB;AAClB,EAAC;AAED,OAAO,MAAME,qCAA8D;IACzEZ,MAAM;IACNC,UAAUJ;IACVK,OAAO;IACPC,aACE;IACFC,MAAM;IACNC,UAAU;IACVC,OAAO;IACPC,MACE;IACFC,UAAU;IACVC,qBAAqB,KAAKX;IAC1BY,gBAAgB;AAClB,EAAC;AAED,OAAO,MAAMG,+BAAwD;IACnEb,MAAM;IACNC,UAAUJ;IACVK,OAAO;IACPC,aACE;IACFC,MAAM;IACNC,UAAU;IACVC,OAAO;IACPC,MAAM;IACNC,UAAU;IACVC,qBAAqB,IAAIX;IACzBY,gBAAgB;AAClB,EAAC;AAED,OAAO,MAAMI,2BAA+D;IAC1Ef;IACAY;IACAC;IACAC;CACD,CAAA"}

package/src/lib/declarations.server.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @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.
+ */
+/**
+ * The commerce plugin's server declarations: the light registrations core
+ * reads at boot, before any surface loads.
+ *
+ * Its operator alerts (AGL-3377), so Staff → Operator alerts lists them and
+ * staff can switch them before the first one is ever raised.
+ */
+export declare function registerCommerceServerDeclarations(): void;

package/src/lib/declarations.server.js

@@ -0,0 +1,33 @@
+/**
+ * @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.
+ */ // The seam from its own module, not the plugin-manager barrel: boot needs the
+// registry and nothing else, and the barrel reaches the client contexts.
+import { registerOperatorAlerts } from "@aglyn/aglyn/plugin-manager/operator-alerts";
+import { BUNDLE_ID } from "./constants/bundle-common.js";
+import { COMMERCE_OPERATOR_ALERTS } from "./constants/operator-alerts.js";
+/**
+ * The commerce plugin's server declarations: the light registrations core
+ * reads at boot, before any surface loads.
+ *
+ * Its operator alerts (AGL-3377), so Staff → Operator alerts lists them and
+ * staff can switch them before the first one is ever raised.
+ */ export function registerCommerceServerDeclarations() {
+    registerOperatorAlerts(COMMERCE_OPERATOR_ALERTS, {
+        pluginId: BUNDLE_ID
+    });
+}
+
+//# sourceMappingURL=declarations.server.js.map

package/src/lib/declarations.server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/plugins/commerce/src/lib/declarations.server.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n// The seam from its own module, not the plugin-manager barrel: boot needs the\n// registry and nothing else, and the barrel reaches the client contexts.\nimport { registerOperatorAlerts } from '@aglyn/aglyn/plugin-manager/operator-alerts'\nimport { BUNDLE_ID } from './constants/bundle-common'\nimport { COMMERCE_OPERATOR_ALERTS } from './constants/operator-alerts'\n\n/**\n * The commerce plugin's server declarations: the light registrations core\n * reads at boot, before any surface loads.\n *\n * Its operator alerts (AGL-3377), so Staff → Operator alerts lists them and\n * staff can switch them before the first one is ever raised.\n */\nexport function registerCommerceServerDeclarations(): void {\n  registerOperatorAlerts(COMMERCE_OPERATOR_ALERTS, { pluginId: BUNDLE_ID })\n}\n"],"names":["registerOperatorAlerts","BUNDLE_ID","COMMERCE_OPERATOR_ALERTS","registerCommerceServerDeclarations","pluginId"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,8EAA8E;AAC9E,yEAAyE;AACzE,SAASA,sBAAsB,QAAQ,8CAA6C;AACpF,SAASC,SAAS,QAAQ,+BAA2B;AACrD,SAASC,wBAAwB,QAAQ,iCAA6B;AAEtE;;;;;;CAMC,GACD,OAAO,SAASC;IACdH,uBAAuBE,0BAA0B;QAAEE,UAAUH;IAAU;AACzE"}

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',