@aglyn/plugins-commerce 1.0.0-beta.284 → 1.0.0-beta.287

package/src/lib/server/pos-offline-sync.js

@@ -20,12 +20,16 @@ import { FieldValue } from "firebase-admin/firestore";
 import * as CommerceModel from "../model/index.js";
 import { posOfflineFlagLabels, posOfflineSaleTotals, posOfflineSoldAt, posOfflineTotalsAddUp, POS_OFFLINE_CARD_INTENT_KIND, POS_OFFLINE_LATE_SYNC_MS, POS_OFFLINE_SYNC_BATCH_MAX, sanitizePosOfflineSale } from "../model/commerce-pos-offline.js";
 import { ORDER_PAID_EVENT } from "../model/order-events.js";
+import { holdsPosPermission } from "../model/plugin-permissions.js";
 import { posMaxDiscountPct, posOfflineCardSettings } from "../plugin-config.js";
 import { alertLowStockCrossing } from "./low-stock.js";
 import { notifyOrderBuyer } from "./order-notifications.js";
 import { raiseOrderEvent } from "./order-events.js";
 import { offlineFeeMonthKey } from "./pos-fee-month.js";
 import { authorizePosOps, defaultPosOpsDeps, posOpsBody, posOpsCleanId, resolvePosStaffAssertion } from "./pos-ops-gate.js";
+import { posOfflineCardChargeRef, reportPosOfflineCardWrongAccount } from "./pos-offline-card-reconcile.js";
+import { posHardwareSaleFields } from "./pos-hardware-sale-fields.js";
+import { posOfflineCardOrderMoney } from "./pos-offline-card-order.js";
 import { notifyPosSaleCompleted } from "./pos-sale.js";
 import { POS_CURRENCY, posCardApplicationFeeCents, posTerminalAvailable } from "./pos-stripe.js";
 import { capturePosOfflineCardIntent, ensurePosOfflineCardConfiguration, posMerchantAccount, posTerminalLocationId, retrievePosOfflineCardIntent } from "./pos-terminal.js";
@@ -39,7 +43,8 @@ export function defaultPosOfflineCardDeps() {
         merchantAccount: posMerchantAccount,
         enableOffline: ensurePosOfflineCardConfiguration,
         retrieve: retrievePosOfflineCardIntent,
-        capture: capturePosOfflineCardIntent
+        capture: capturePosOfflineCardIntent,
+        wrongAccount: reportPosOfflineCardWrongAccount
     };
 }
 export function defaultPosOfflineSyncDeps() {
@@ -261,12 +266,44 @@ async function readStoreTax(staff) {
         available: true
     });
 }
+/** Statuses in which an intent holds the customer's money or has taken it. */ const INTENT_HOLDS_MONEY = new Set([
+    'requires_capture',
+    'processing',
+    'succeeded'
+]);
+/**
+ * How long after a capture that Stripe answered with a 5xx the sync waits
+ * before reading "still waiting for capture" as the definite answer.
+ */ export const POS_OFFLINE_CAPTURE_SETTLE_MS = 60000;
+/**
+ * The capture's idempotency key (AGL-4039). Attempt 0 is the key every
+ * capture used before attempts existed, so a retry of one already in flight
+ * still finds it.
+ *
+ * WHY AN ATTEMPT. Stripe keeps the answer to an idempotent request for a day,
+ * failures included, so a capture that failed once on a per-sale key would
+ * fail the same way on every sync for a day, deep into the two days the
+ * authorization lasts. The attempt moves on only when the previous one
+ * DEFINITELY did not capture: Stripe refused it with a 4xx (not 409, a
+ * request with the same key still running, and not 429, rate limited), or it
+ * answered 5xx and the intent still waits for capture a minute later. A
+ * request that got no answer at all throws before anything is recorded, so it
+ * retries on the same key. Every sync reads the intent before it captures,
+ * and Stripe captures an intent once, so a new key can never capture twice.
+ */ export function posOfflineCaptureKey(hostId, saleKey, attempt) {
+    const base = `pos-offline-capture:${hostId}:${saleKey}`;
+    return attempt > 0 ? `${base}:${attempt}` : base;
+}
+/** A capture Stripe refused for good: retrying the same key would replay the refusal. */ export function posOfflineCaptureRefused(status) {
+    return typeof status === 'number' && status >= 400 && status < 500 && status !== 409 && status !== 429;
+}
 /**
  * Reads the card of a sale rung offline and settles it: captured with the
  * platform fee (the card tender's share of the take, by the one tender rule,
  * plus Stripe's processing cost, exactly as an online reader payment), or
- * unpaid when the bank declined it or Stripe never took it. Anything Stripe
- * has not finished yet waits on the register for the next sync.
+ * unpaid when the bank declined it, Stripe never took it, or it was made out
+ * to a Stripe account that is not the store's. Anything Stripe has not
+ * finished yet waits on the register for the next sync.
  */ async function settleOfflineCard(context, sale, takeFee) {
     const { deps, staff } = context;
     const { saleKey } = sale;
@@ -292,7 +329,10 @@ async function readStoreTax(staff) {
     const read = await deps.card.retrieve(card.paymentIntentId);
     if ('error' in read) return wait(`The card payment could not be checked yet: ${read.error}`);
     let intent = read.intent;
-    if (intent.metadata['kind'] !== POS_OFFLINE_CARD_INTENT_KIND || intent.metadata['saleKey'] !== saleKey || intent.metadata['hostId'] !== staff.hostId || intent.amount !== sale.totals.totalCents || intent.currency !== POS_CURRENCY) {
+    // The amount is NOT checked here: what Stripe took is what the customer
+    // paid, and a difference from the server's total is flagged on the order
+    // (`posOfflineCardOrderMoney`), never a reason to leave the sale unrecorded.
+    if (intent.metadata['kind'] !== POS_OFFLINE_CARD_INTENT_KIND || intent.metadata['saleKey'] !== saleKey || intent.metadata['hostId'] !== staff.hostId || intent.currency !== POS_CURRENCY) {
         return {
             kind: 'wait',
             outcome: refused(saleKey, 'invalid', 'The card payment does not belong to this sale.', false)
@@ -303,21 +343,87 @@ async function readStoreTax(staff) {
     } : {}, intent.last4 ? {
         last4: intent.last4
     } : {});
+    // THE DESTINATION. The device made this intent out to the account its
+    // offline kit named, and a kit can be stale (the store reconnected Stripe)
+    // or a register tampered with. Money that holds or has moved is only ever
+    // captured into, or recorded as paid to, the store's account as it is now.
+    if (INTENT_HOLDS_MONEY.has(intent.status)) {
+        const expected = await deps.card.merchantAccount(staff.hostId, staff.org);
+        if (!expected) {
+            return wait('This store’s Stripe account cannot take card payments right now. The card syncs once it can.');
+        }
+        if (intent.destination !== expected) {
+            return _extends({
+                kind: 'unpaid',
+                flag: 'card-not-charged',
+                intentId: intent.id,
+                message: 'The card was made out to a Stripe account that is not this store’s, so it was not charged here.'
+            }, found, {
+                wrongAccount: {
+                    destination: intent.destination,
+                    expected,
+                    status: intent.status,
+                    amountCents: intent.amount
+                }
+            });
+        }
+    }
     const takeShareCents = CommerceModel.posTenderTakeCents('card_present', takeFee);
+    const expectedFeeCents = posCardApplicationFeeCents({
+        takeShareCents,
+        chargeCents: intent.amount
+    });
     if (intent.status === 'requires_capture') {
-        const feeCents = posCardApplicationFeeCents({
-            takeShareCents,
-            chargeCents: intent.amount
-        });
-        const captured = await deps.card.capture(intent.id, feeCents, `pos-offline-capture:${staff.hostId}:${saleKey}`);
-        if ('error' in captured) return wait(`The card payment could not be captured yet: ${captured.error}`);
+        var _data, _charge_captureAttempt, _charge_captureUncertainAtMs;
+        const chargeRef = posOfflineCardChargeRef(staff.hostRef, saleKey);
+        const charge = (_data = (await chargeRef.get()).data()) != null ? _data : {};
+        let attempt = Math.max(0, Math.round(Number((_charge_captureAttempt = charge['captureAttempt']) != null ? _charge_captureAttempt : 0)) || 0);
+        if (charge['captureUncertainAttempt'] === attempt && deps.now() - Number((_charge_captureUncertainAtMs = charge['captureUncertainAtMs']) != null ? _charge_captureUncertainAtMs : 0) >= POS_OFFLINE_CAPTURE_SETTLE_MS) {
+            // The 5xx left the outcome unknown; the intent still waiting for
+            // capture a minute later says it did not capture.
+            attempt += 1;
+            await chargeRef.set({
+                captureAttempt: attempt,
+                captureUncertainAttempt: FieldValue.delete(),
+                captureUncertainAtMs: FieldValue.delete()
+            }, {
+                merge: true
+            });
+        }
+        const captured = await deps.card.capture(intent.id, expectedFeeCents, posOfflineCaptureKey(staff.hostId, saleKey, attempt));
+        if ('error' in captured) {
+            const stamp = {
+                hostId: staff.hostId,
+                saleKey,
+                updatedAtMs: deps.now()
+            };
+            if (posOfflineCaptureRefused(captured.status)) {
+                await chargeRef.set(_extends({}, stamp, {
+                    captureAttempt: attempt + 1,
+                    lastCaptureStatus: captured.status,
+                    lastCaptureError: captured.error.slice(0, 300)
+                }), {
+                    merge: true
+                });
+            } else if (typeof captured.status === 'number' && captured.status >= 500) {
+                await chargeRef.set(_extends({}, stamp, {
+                    captureUncertainAttempt: attempt,
+                    captureUncertainAtMs: deps.now()
+                }), {
+                    merge: true
+                });
+            }
+            return wait(`The card payment could not be captured yet: ${captured.error}`);
+        }
         intent = captured.intent;
     }
     if (intent.status === 'succeeded') {
         return _extends({
             kind: 'captured',
             intentId: intent.id,
+            amountCents: intent.amount,
             feeCents: intent.applicationFeeCents,
+            expectedFeeCents,
             takeShareCents,
             livemode: intent.livemode
         }, found);
@@ -484,7 +590,7 @@ const replayOf = (record)=>({
     return current;
 }
 async function syncOne(context, raw) {
-    var _ref, _sale_customer;
+    var _ref, _staff_orgId, _ref1, _sale_customer;
     const { deps, staff } = context;
     const read = sanitizePosOfflineSale(raw);
     const rawKey = String((_ref = raw == null ? void 0 : raw['saleKey']) != null ? _ref : '').slice(0, 64);
@@ -618,6 +724,13 @@ async function syncOne(context, raw) {
         flags.add('tax-differs');
     }
     if (sale.discountPct > posMaxDiscountPct(context.config)) flags.add('discount-over-limit');
+    // The cashier's own discount needs `posDiscount` (AGL-4047), as the online
+    // register refuses it without. Offline the sale has already happened, so it
+    // is recorded and flagged rather than dropped. Read for the member who was
+    // signed in, whose membership the gate resolved, as the online check reads it.
+    if (sale.discountPct > 0 && !holdsPosPermission(staff.membership.permissions, 'posDiscount')) {
+        flags.add('discount-not-permitted');
+    }
     const byCard = sale.tender === 'card';
     if (!byCard && sale.cashTenderedCents < totals.totalCents) flags.add('cash-short');
     // Where it was rung.
@@ -648,21 +761,36 @@ async function syncOne(context, raw) {
         if (memberUid) cashierId = memberUid;
         else flags.add('cashier-unverified');
     }
-    // The offline register takes cash only, and cash carries no platform fee
-    // (AGL-4036): the plan's take is worked out and then settled by the one
-    // predicate every tender answers to, so a sale synced from the queue is
-    // charged exactly what the same sale rung online is.
+    // Cash carries no platform fee (AGL-4036): the plan's take is worked out
+    // and then settled by the one predicate every tender answers to, so a sale
+    // synced from the queue is charged exactly what the same sale rung online
+    // is.
     const planTake = takeFeeCents(deps, staff, lineItems, totals);
     // A card taken offline settles with Stripe BEFORE the order is written: a
     // capture that fails leaves the sale on the register for the next sync,
     // and a repeat after a lost answer finds the first capture (AGL-4039).
     const settled = byCard ? await settleOfflineCard(context, sale, planTake) : null;
     if ((settled == null ? void 0 : settled.kind) === 'wait') return settled.outcome;
-    if ((settled == null ? void 0 : settled.kind) === 'unpaid') flags.add(settled.flag);
-    const takeFee = byCard ? (settled == null ? void 0 : settled.kind) === 'captured' ? settled.takeShareCents : 0 : CommerceModel.posTenderTakeCents('cash', planTake);
-    totals = _extends({}, totals, {
-        feeCents: takeFee
+    // The card's money, decided once against the server's totals: the fee it
+    // settled, the shortfall to invoice, and the order-level intent the refund
+    // and the dispute lookup read.
+    const cardMoney = settled ? posOfflineCardOrderMoney({
+        settled,
+        totals,
+        planTakeCents: planTake,
+        soldAtMs: soldAt.atMs,
+        nowMs: now,
+        cashierId,
+        feeOrgId: (_staff_orgId = staff.orgId) != null ? _staff_orgId : ''
+    }) : null;
+    for (const flag of (_ref1 = cardMoney == null ? void 0 : cardMoney.flags) != null ? _ref1 : [])flags.add(flag);
+    const cashTake = CommerceModel.posTenderTakeCents('cash', planTake);
+    totals = cardMoney ? cardMoney.totals : _extends({}, totals, {
+        feeCents: cashTake
     });
+    // What accrues to the org's month with the order: the cash take (none
+    // since AGL-4036) or the part of a card's fee its payout did not carry.
+    const invoiceCents = cardMoney ? cardMoney.invoiceCents : cashTake;
     const changeCents = byCard ? 0 : Math.max(0, sale.cashTenderedCents - totals.totalCents);
     const flagList = [
         ...flags
@@ -701,7 +829,7 @@ async function syncOne(context, raw) {
             settled.brand ? settled.brand.toUpperCase() : 'Card',
             settled.last4 ? `•••• ${settled.last4}` : ''
         ].filter(Boolean).join(' ') : '';
-        const paidDetail = !settled ? `Cash — received ${money(sale.cashTenderedCents)}, change ${money(changeCents)}. ` + 'Rung while the register was offline.' : settled.kind === 'captured' ? `${cardName} — ${money(totals.totalCents)}, taken while the register was offline and charged when it reconnected.` : `${cardName} — ${money(totals.totalCents)} taken while the register was offline was not paid: ${settled.message}`.slice(0, 500);
+        const paidDetail = !settled ? `Cash — received ${money(sale.cashTenderedCents)}, change ${money(changeCents)}. ` + 'Rung while the register was offline.' : settled.kind === 'captured' ? `${cardName} — ${money(settled.amountCents)}, taken while the register was offline and charged when it reconnected.` : `${cardName} — ${money(totals.totalCents)} taken while the register was offline was not paid: ${settled.message}`.slice(0, 500);
         const timeline = [
             {
                 atMs: soldAt.atMs,
@@ -716,7 +844,7 @@ async function syncOne(context, raw) {
         ];
         transaction.create(orderRef, CommerceModel.withOrderListFields(orderRef.id, _extends({
             number,
-            status: (settled == null ? void 0 : settled.kind) === 'unpaid' ? 'pending' : 'paid',
+            status: cardMoney ? cardMoney.status : 'paid',
             channel: 'pos',
             registerId: sale.registerId,
             cashierId
@@ -734,38 +862,20 @@ async function syncOne(context, raw) {
             discountBy: cashierId
         } : {}, sale.locationId ? {
             locationId: sale.locationId
-        } : {}, {
+        } : {}, posHardwareSaleFields({
+            hostId: staff.hostId,
+            orgId: staff.orgId,
+            lineItems,
+            products
+        }), {
             lineItems,
             totals,
             taxMode: 'decision' in context.tax ? CommerceModel.storefrontTaxModeForDecision(context.tax.decision, totals.taxCents) : totals.taxCents > 0 ? 'manual' : 'none'
-        }, takeFee > 0 ? {
-            feeCollection: settled ? 'payout' : 'invoice'
+        }, cardMoney ? cardMoney.fields : cashTake > 0 ? {
+            feeCollection: 'invoice'
         } : {}, {
-            payments: settled ? [
-                _extends({
-                    id: 'pay_card_offline',
-                    method: 'card_present',
-                    amountCents: totals.totalCents,
-                    status: settled.kind === 'captured' ? 'succeeded' : 'failed',
-                    atMs: soldAt.atMs
-                }, settled.kind === 'captured' ? {
-                    settledAtMs: now,
-                    takeFeeCents: settled.takeShareCents,
-                    feeCents: settled.feeCents,
-                    livemode: settled.livemode
-                } : {
-                    takeFeeCents: 0,
-                    feeCents: 0,
-                    failureMessage: settled.message.slice(0, 300)
-                }, settled.intentId ? {
-                    paymentIntentId: settled.intentId
-                } : {}, settled.brand ? {
-                    cardBrand: settled.brand
-                } : {}, settled.last4 ? {
-                    last4: settled.last4
-                } : {}, {
-                    cashierId
-                })
+            payments: cardMoney ? [
+                cardMoney.payment
             ] : [
                 {
                     id: 'pay_cash',
@@ -774,7 +884,7 @@ async function syncOne(context, raw) {
                     status: 'succeeded',
                     atMs: soldAt.atMs,
                     settledAtMs: soldAt.atMs,
-                    takeFeeCents: takeFee,
+                    takeFeeCents: cashTake,
                     feeCents: 0,
                     cashierId,
                     cashTenderedCents: sale.cashTenderedCents,
@@ -805,12 +915,30 @@ async function syncOne(context, raw) {
             unpaid: true
         } : {});
         transaction.create(recordRef, record);
-        // The take accrues with the order, in the same transaction (AGL-2111).
-        // A card's share was netted from its payout by the capture instead.
-        if (takeFee > 0 && feeRef && !settled) {
+        // The intent's record says its sale synced, in the same commit, so the
+        // webhook and the unsynced-card sweep never report a sale that landed.
+        if (settled == null ? void 0 : settled.intentId) {
+            transaction.set(posOfflineCardChargeRef(hostRef, sale.saleKey), {
+                hostId: staff.hostId,
+                saleKey: sale.saleKey,
+                paymentIntentId: settled.intentId,
+                registerId: sale.registerId,
+                synced: true,
+                orderId: orderRef.id,
+                syncedAtMs: now,
+                updatedAtMs: now,
+                alertDueAtMs: FieldValue.delete()
+            }, {
+                merge: true
+            });
+        }
+        // The fee no payout carried accrues with the order, in the same
+        // transaction (AGL-2111): a card's share was netted from its payout by
+        // the capture, and only a shortfall in that lands here.
+        if (invoiceCents > 0 && feeRef) {
             transaction.set(feeRef, {
                 month: feeMonth,
-                feeCents: FieldValue.increment(takeFee),
+                feeCents: FieldValue.increment(invoiceCents),
                 orders: FieldValue.increment(1)
             }, {
                 merge: true
@@ -830,6 +958,13 @@ async function syncOne(context, raw) {
         }
         return replayOf(record);
     }
+    if ((settled == null ? void 0 : settled.kind) === 'unpaid' && settled.wrongAccount && settled.intentId) {
+        await deps.card.wrongAccount(_extends({
+            hostId: staff.hostId,
+            orderId: orderRef.id,
+            paymentIntentId: settled.intentId
+        }, settled.wrongAccount));
+    }
     const finished = await finishSale(context, recordRef, orderRef, committed.record);
     return {
         saleKey: sale.saleKey,
@@ -854,7 +989,7 @@ export async function handlePosOfflineSync(deps, req) {
             key,
             Array.isArray(value) ? value[0] : value
         ])) : posOpsBody(req);
-    const gate = await authorizePosOps(deps, req, body['hostId']);
+    const gate = await authorizePosOps(deps, req, body['hostId'], 'posSell');
     if ('error' in gate) return {
         status: gate.status,
         body: {