@aglyn/plugins-commerce 1.0.0-beta.285 → 1.0.0-beta.288

package/src/lib/server/pos-offline-card-reconcile.d.ts

@@ -14,9 +14,18 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { BillingWebhookHandler } from '@aglyn/aglyn/server';
+import type { BillingWebhookHandler, PluginJobHostGate } from '@aglyn/aglyn/server';
+/** The subcollection, under `hosts/{hostId}/terminal/config`, and its collection-group name. */
+export declare const POS_OFFLINE_CARD_CHARGES = "offlineCardCharges";
+/**
+ * How long an intent that holds money may wait for its sale before the sweep
+ * says so: six hours, which leaves well over a day of Stripe's two-day
+ * authorization to sync it, and is far past the seconds a healthy sync takes.
+ */
+export declare const POS_OFFLINE_CARD_UNSYNCED_ALERT_MS: number;
 /** What the site keeps about one offline card's PaymentIntent. */
 export interface PosOfflineCardChargeRecord {
+    hostId: string;
     saleKey: string;
     paymentIntentId: string;
     status: string;
@@ -25,9 +34,18 @@ export interface PosOfflineCardChargeRecord {
     livemode: boolean;
     /** Whether the sale has synced (its order exists). */
     synced: boolean;
+    orderId?: string;
+    syncedAtMs?: number;
     lastEvent: string;
     updatedAtMs: number;
+    /** When the sweep says the sale never synced; absent once synced or told. */
+    alertDueAtMs?: number;
+    alertedAtMs?: number;
+    /** The capture's idempotency attempt, raised only after a definite failure. */
+    captureAttempt?: number;
 }
+/** `hosts/{hostId}/terminal/config/offlineCardCharges/{saleKey}`. */
+export declare function posOfflineCardChargeRef(hostRef: FirebaseFirestore.DocumentReference, saleKey: string): FirebaseFirestore.DocumentReference;
 export declare function reconcilePosOfflineCardEvent(input: {
     type: string;
     object: any;
@@ -36,3 +54,51 @@ export declare function reconcilePosOfflineCardEvent(input: {
 } | null>;
 /** The platform webhook's handler for offline card intents: claims only its own. */
 export declare const posOfflineCardBillingWebhookHandler: BillingWebhookHandler;
+export interface UnsyncedOfflineCardReport {
+    hostId: string;
+    saleKey: string;
+    paymentIntentId: string;
+    status: string;
+    amountCents: number;
+    registerId: string;
+    /** How long ago the intent was first seen waiting, in ms. */
+    waitedMs: number;
+}
+export interface UnsyncedOfflineCardScan {
+    due: number;
+    alerted: number;
+    /** Synced, or no longer holding money, since the alert was set. */
+    cleared: number;
+    skippedLocked: number;
+}
+/** Tells the operator and the site's managers about one card. Never throws. */
+export declare function reportUnsyncedOfflineCard(report: UnsyncedOfflineCardReport): Promise<void>;
+/** Tells the operator a card was made out to an account that is not the store's. Never throws. */
+export declare function reportPosOfflineCardWrongAccount(input: {
+    hostId: string;
+    orderId: string;
+    paymentIntentId: string;
+    status: string;
+    amountCents: number;
+    destination: string;
+    expected: string;
+}): Promise<void>;
+/**
+ * The hourly sweep (registered in `server.ts`): every offline card record
+ * whose alert is due. Re-checks the sale first, so a sale that synced while
+ * the event was in flight clears the record and tells nobody.
+ *
+ * One collection-group range query on `alertDueAtMs`, which is set only on a
+ * record that holds money and has not synced, so the ordinary beat reads an
+ * empty result. Its COLLECTION_GROUP index is declared in
+ * `cloud/firebase-firestore.indexes.json` and pinned by
+ * `cron-scan-indexes.spec.ts`.
+ */
+export declare function scanUnsyncedOfflineCards(
+/** The lockdown gate, injected by the runner (AGL-2495). */
+gate: PluginJobHostGate, options?: {
+    firestore?: FirebaseFirestore.Firestore;
+    nowMs?: number;
+    limit?: number;
+    report?: (report: UnsyncedOfflineCardReport) => Promise<void>;
+}): Promise<UnsyncedOfflineCardScan>;

package/src/lib/server/pos-offline-card-reconcile.js

@@ -1,3 +1,4 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
 /**
  * @license
  * Copyright 2026 Aglyn LLC
@@ -13,32 +14,102 @@
  * 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 { firebaseAdmin } from "@aglyn/tenant-data-admin";
+ */ import { formatOperatorAlertAmount } from "@aglyn/aglyn/app-utils/operator-alerts";
+import { firebaseAdmin, hostDisplayName, notifyHostManagers, raiseOperatorAlert } from "@aglyn/tenant-data-admin";
+import { FieldValue } from "firebase-admin/firestore";
+import { COMMERCE_POS_OFFLINE_CARD_UNSYNCED, COMMERCE_POS_OFFLINE_CARD_WRONG_ACCOUNT } from "../constants/operator-alerts.js";
 import { POS_OFFLINE_CARD_INTENT_KIND, posOfflineSaleKeyIsValid } from "../model/commerce-pos-offline.js";
+/*==========================================
+ * A CARD TAKEN OFFLINE, AS STRIPE REPORTS IT (AGL-4039).
+ *
+ * The Aglyn POS app creates the PaymentIntent of a card it takes offline, so
+ * Stripe can know of a charge before the sale itself reaches the server: the
+ * SDK forwards the card the moment a connection returns, and the sale syncs
+ * right after, from the same device. Usually seconds apart. If the sale never
+ * arrives (the device was lost or wiped between the two, or it waits for a
+ * member who never signs in again), the charge must not be invisible: each
+ * event on such an intent is kept on the site, by the sale's key, under the
+ * site's server-only Terminal document
+ * (`terminal/config/offlineCardCharges/{saleKey}`), beside whether the sale
+ * has synced. The sync itself never depends on this: it reads Stripe.
+ *
+ * WHO SAYS "SYNCED". Both writers, in transactions, so neither can undo the
+ * other: the sync marks the record when it creates the order, and an event
+ * reads the record and the sync record together. An event that arrives after
+ * the sync therefore keeps `synced`, and one that raced it retries and sees
+ * it.
+ *
+ * NOBODY LOOKING. An intent that holds or has taken money while its sale has
+ * not synced gets `alertDueAtMs`, {@link POS_OFFLINE_CARD_UNSYNCED_ALERT_MS}
+ * after it was first seen. The hourly sweep ({@link scanUnsyncedOfflineCards})
+ * tells the operator and the site's managers once, with time left to sync the
+ * sale before Stripe's authorization lapses (about two days). It never
+ * captures: without the sale there is no fee to capture with.
+ *
+ * Self-selecting: every other event returns `null` untouched. Registered on
+ * the platform webhook from the commerce server module, beside the other
+ * commerce handlers, rather than as a branch of the storefront sections. The
+ * four `payment_intent.*` events it reads are in the platform destination's
+ * `WEBHOOK_EVENTS` (`tools/scripts/lib/stripe-webhook-health.mjs`).
+ *=========================================*/ /** The subcollection, under `hosts/{hostId}/terminal/config`, and its collection-group name. */ export const POS_OFFLINE_CARD_CHARGES = 'offlineCardCharges';
+/**
+ * How long an intent that holds money may wait for its sale before the sweep
+ * says so: six hours, which leaves well over a day of Stripe's two-day
+ * authorization to sync it, and is far past the seconds a healthy sync takes.
+ */ export const POS_OFFLINE_CARD_UNSYNCED_ALERT_MS = 6 * 60 * 60 * 1000;
+/** Statuses in which an intent holds money or has taken it. */ const HOLDS_MONEY = new Set([
+    'requires_capture',
+    'processing',
+    'succeeded'
+]);
+/** Statuses an intent never leaves; an older event must not turn one back. */ const FINAL = new Set([
+    'succeeded',
+    'canceled'
+]);
+/** `hosts/{hostId}/terminal/config/offlineCardCharges/{saleKey}`. */ export function posOfflineCardChargeRef(hostRef, saleKey) {
+    return hostRef.collection('terminal').doc('config').collection(POS_OFFLINE_CARD_CHARGES).doc(saleKey);
+}
+const validHostId = (hostId)=>/^[A-Za-z0-9_-]{1,128}$/.test(hostId);
 export async function reconcilePosOfflineCardEvent(input, firestore, now = Date.now) {
-    var _input_object, _intent_metadata, _metadata_hostId, _metadata_saleKey, _intent_id, _intent_status, _intent_amount, _metadata_registerId;
+    var _input_object, _intent_metadata, _metadata_hostId, _metadata_saleKey;
     if (!input.type.startsWith('payment_intent.')) return null;
     const intent = (_input_object = input.object) != null ? _input_object : {};
     const metadata = (_intent_metadata = intent.metadata) != null ? _intent_metadata : {};
     if (metadata['kind'] !== POS_OFFLINE_CARD_INTENT_KIND) return null;
     const hostId = String((_metadata_hostId = metadata['hostId']) != null ? _metadata_hostId : '');
     const saleKey = String((_metadata_saleKey = metadata['saleKey']) != null ? _metadata_saleKey : '');
-    if (!/^[A-Za-z0-9_-]{1,128}$/.test(hostId) || !posOfflineSaleKeyIsValid(saleKey)) return null;
-    const hostRef = (firestore != null ? firestore : firebaseAdmin.app().firestore()).collection('hosts').doc(hostId);
-    const synced = (await hostRef.collection('posOfflineSales').doc(saleKey).get()).exists;
-    const record = {
-        saleKey,
-        paymentIntentId: String((_intent_id = intent.id) != null ? _intent_id : ''),
-        status: String((_intent_status = intent.status) != null ? _intent_status : ''),
-        amountCents: Number((_intent_amount = intent.amount) != null ? _intent_amount : 0),
-        registerId: String((_metadata_registerId = metadata['registerId']) != null ? _metadata_registerId : '').slice(0, 128),
-        livemode: Boolean(intent.livemode),
-        synced,
-        lastEvent: input.type,
-        updatedAtMs: now()
-    };
-    await hostRef.collection('terminal').doc('config').collection('offlineCardCharges').doc(saleKey).set(record, {
-        merge: true
+    if (!validHostId(hostId) || !posOfflineSaleKeyIsValid(saleKey)) return null;
+    const db = firestore != null ? firestore : firebaseAdmin.app().firestore();
+    const hostRef = db.collection('hosts').doc(hostId);
+    const chargeRef = posOfflineCardChargeRef(hostRef, saleKey);
+    const saleRef = hostRef.collection('posOfflineSales').doc(saleKey);
+    await db.runTransaction(async (transaction)=>{
+        var _intent_status, _intent_id, _intent_amount, _metadata_registerId;
+        const charge = await transaction.get(chargeRef);
+        const sale = await transaction.get(saleRef);
+        const previous = charge.exists ? charge.data() : {};
+        const synced = previous.synced === true || sale.exists;
+        const incoming = String((_intent_status = intent.status) != null ? _intent_status : '');
+        // Stripe does not promise event order: a late `amount_capturable_updated`
+        // must not turn a captured or canceled intent back into an authorized one.
+        const status = previous.status && FINAL.has(previous.status) && !FINAL.has(incoming) ? previous.status : incoming;
+        const at = now();
+        const alertDueAtMs = !synced && HOLDS_MONEY.has(status) && !previous.alertedAtMs ? typeof previous.alertDueAtMs === 'number' ? previous.alertDueAtMs : at + POS_OFFLINE_CARD_UNSYNCED_ALERT_MS : null;
+        transaction.set(chargeRef, {
+            hostId,
+            saleKey,
+            paymentIntentId: String((_intent_id = intent.id) != null ? _intent_id : ''),
+            status,
+            amountCents: Math.max(0, Math.round(Number((_intent_amount = intent.amount) != null ? _intent_amount : 0))),
+            registerId: String((_metadata_registerId = metadata['registerId']) != null ? _metadata_registerId : '').slice(0, 128),
+            livemode: Boolean(intent.livemode),
+            synced,
+            lastEvent: input.type,
+            updatedAtMs: at,
+            alertDueAtMs: alertDueAtMs != null ? alertDueAtMs : FieldValue.delete()
+        }, {
+            merge: true
+        });
     });
     return {
         hostId
@@ -54,5 +125,131 @@ export async function reconcilePosOfflineCardEvent(input, firestore, now = Date.
         hostId: reconciled.hostId
     } : undefined;
 };
+const describeWait = (ms)=>{
+    const hours = Math.max(1, Math.round(ms / (60 * 60 * 1000)));
+    return hours >= 48 ? `${Math.round(hours / 24)} days` : `${hours} hour${hours === 1 ? '' : 's'}`;
+};
+/** Tells the operator and the site's managers about one card. Never throws. */ export async function reportUnsyncedOfflineCard(report) {
+    try {
+        const host = await firebaseAdmin.app().firestore().collection('hosts').doc(report.hostId).get().catch(()=>null);
+        const site = (host == null ? void 0 : host.exists) ? hostDisplayName(host.data(), report.hostId) : report.hostId;
+        const amount = formatOperatorAlertAmount(report.amountCents);
+        await raiseOperatorAlert(COMMERCE_POS_OFFLINE_CARD_UNSYNCED, {
+            dedupeKey: `${report.hostId}:${report.saleKey}`,
+            hostId: report.hostId,
+            context: {
+                amount,
+                paymentIntentId: report.paymentIntentId,
+                status: report.status,
+                site: `${site} (${report.hostId})`,
+                registerId: report.registerId || 'unknown',
+                age: describeWait(report.waitedMs)
+            }
+        });
+        await notifyHostManagers(report.hostId, {
+            type: 'content.order',
+            title: `A ${amount} card taken offline on {site} has no sale`,
+            body: report.status === 'succeeded' ? `A ${amount} card taken offline was charged, but the register never sent its sale, so there is no order for it. ` + 'Open the register that took it, signed in as the member who rang it, so the sale syncs.' : `A ${amount} card taken offline is approved but not yet charged, because the register never sent its sale. ` + 'Open the register that took it, signed in as the member who rang it, so the sale syncs. ' + 'If it does not sync within about two days of the sale, the card is never charged.',
+            link: `/${report.hostId}/products`
+        });
+    } catch (error) {
+        console.error('[pos-offline-card] unsynced report failed', report.hostId, report.saleKey, error);
+    }
+}
+/** Tells the operator a card was made out to an account that is not the store's. Never throws. */ export async function reportPosOfflineCardWrongAccount(input) {
+    try {
+        const host = await firebaseAdmin.app().firestore().collection('hosts').doc(input.hostId).get().catch(()=>null);
+        const site = (host == null ? void 0 : host.exists) ? hostDisplayName(host.data(), input.hostId) : input.hostId;
+        await raiseOperatorAlert(COMMERCE_POS_OFFLINE_CARD_WRONG_ACCOUNT, {
+            dedupeKey: `${input.hostId}:${input.orderId}`,
+            hostId: input.hostId,
+            context: {
+                amount: formatOperatorAlertAmount(input.amountCents),
+                paymentIntentId: input.paymentIntentId,
+                status: input.status,
+                orderId: input.orderId,
+                site: `${site} (${input.hostId})`,
+                destination: input.destination || 'none',
+                expected: input.expected
+            }
+        });
+    } catch (error) {
+        console.error('[pos-offline-card] wrong-account alert failed', input.hostId, input.orderId, error);
+    }
+}
+/**
+ * The hourly sweep (registered in `server.ts`): every offline card record
+ * whose alert is due. Re-checks the sale first, so a sale that synced while
+ * the event was in flight clears the record and tells nobody.
+ *
+ * One collection-group range query on `alertDueAtMs`, which is set only on a
+ * record that holds money and has not synced, so the ordinary beat reads an
+ * empty result. Its COLLECTION_GROUP index is declared in
+ * `cloud/firebase-firestore.indexes.json` and pinned by
+ * `cron-scan-indexes.spec.ts`.
+ */ export async function scanUnsyncedOfflineCards(/** The lockdown gate, injected by the runner (AGL-2495). */ gate, options = {}) {
+    var _options_firestore, _options_nowMs, _options_report, _options_limit;
+    const db = (_options_firestore = options.firestore) != null ? _options_firestore : firebaseAdmin.app().firestore();
+    const nowMs = (_options_nowMs = options.nowMs) != null ? _options_nowMs : Date.now();
+    const report = (_options_report = options.report) != null ? _options_report : reportUnsyncedOfflineCard;
+    const scan = {
+        due: 0,
+        alerted: 0,
+        cleared: 0,
+        skippedLocked: 0
+    };
+    const due = await db.collectionGroup(POS_OFFLINE_CARD_CHARGES).where('alertDueAtMs', '<=', nowMs).orderBy('alertDueAtMs', 'asc').limit((_options_limit = options.limit) != null ? _options_limit : 100).get().catch((error)=>{
+        console.error('[pos-offline-card] unsynced scan failed', error);
+        return null;
+    });
+    if (!due) return scan;
+    for (const doc of due.docs){
+        var _doc_data, _record_status, _record_paymentIntentId, _record_status1, _record_amountCents, _record_registerId;
+        var _doc_ref_parent_parent_parent_parent, _doc_ref_parent_parent_parent, _doc_ref_parent_parent;
+        const record = (_doc_data = doc.data()) != null ? _doc_data : {};
+        if (typeof record.alertDueAtMs !== 'number') continue;
+        // `hosts/{hostId}/terminal/config/offlineCardCharges/{saleKey}`.
+        const hostId = String(record.hostId || ((_doc_ref_parent_parent = doc.ref.parent.parent) == null ? void 0 : (_doc_ref_parent_parent_parent = _doc_ref_parent_parent.parent) == null ? void 0 : (_doc_ref_parent_parent_parent_parent = _doc_ref_parent_parent_parent.parent) == null ? void 0 : _doc_ref_parent_parent_parent_parent.id) || '');
+        const saleKey = String(record.saleKey || doc.id);
+        if (!validHostId(hostId) || !posOfflineSaleKeyIsValid(saleKey)) continue;
+        scan.due += 1;
+        // A locked site is skipped, not dropped: its record stays due and is
+        // told on the first beat after the lift.
+        if (await gate.isLocked(hostId)) {
+            scan.skippedLocked += 1;
+            continue;
+        }
+        const hostRef = db.collection('hosts').doc(hostId);
+        const synced = (await hostRef.collection('posOfflineSales').doc(saleKey).get()).exists;
+        if (synced || !HOLDS_MONEY.has(String((_record_status = record.status) != null ? _record_status : ''))) {
+            await doc.ref.set(_extends({}, synced ? {
+                synced: true
+            } : {}, {
+                alertDueAtMs: FieldValue.delete()
+            }), {
+                merge: true
+            });
+            scan.cleared += 1;
+            continue;
+        }
+        await report({
+            hostId,
+            saleKey,
+            paymentIntentId: String((_record_paymentIntentId = record.paymentIntentId) != null ? _record_paymentIntentId : ''),
+            status: String((_record_status1 = record.status) != null ? _record_status1 : ''),
+            amountCents: Math.max(0, Math.round(Number((_record_amountCents = record.amountCents) != null ? _record_amountCents : 0))),
+            registerId: String((_record_registerId = record.registerId) != null ? _record_registerId : ''),
+            waitedMs: Math.max(0, nowMs - (record.alertDueAtMs - POS_OFFLINE_CARD_UNSYNCED_ALERT_MS))
+        });
+        await doc.ref.set({
+            alertedAtMs: nowMs,
+            alertDueAtMs: FieldValue.delete()
+        }, {
+            merge: true
+        });
+        scan.alerted += 1;
+    }
+    return scan;
+}
 
 //# sourceMappingURL=pos-offline-card-reconcile.js.map

package/src/lib/server/pos-offline-card-reconcile.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/pos-offline-card-reconcile.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 { BillingWebhookHandler } from '@aglyn/aglyn/server'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport {\n  POS_OFFLINE_CARD_INTENT_KIND,\n  posOfflineSaleKeyIsValid,\n} from '../model/commerce-pos-offline'\n\n/*==========================================\n * A CARD TAKEN OFFLINE, AS STRIPE REPORTS IT (AGL-4039).\n *\n * The Aglyn POS app creates the PaymentIntent of a card it takes offline, so\n * Stripe can know of a charge before the sale itself reaches the server: the\n * SDK forwards the card the moment a connection returns, and the sale syncs\n * right after, from the same device. Usually seconds apart. If the sale never\n * arrives (the device was lost or wiped between the two), the charge must not\n * be invisible: each event on such an intent is kept on the site, by the\n * sale's key, under the site's server-only Terminal document\n * (`terminal/config/offlineCardCharges/{saleKey}`), beside whether the sale\n * has synced. The sync itself never depends on this: it reads Stripe.\n *\n * Self-selecting: every other event returns `null` untouched. Registered on\n * the platform webhook from the commerce server module, beside the other\n * commerce handlers, rather than as a branch of the storefront sections.\n *=========================================*/\n\n/** What the site keeps about one offline card's PaymentIntent. */\nexport interface PosOfflineCardChargeRecord {\n  saleKey: string\n  paymentIntentId: string\n  status: string\n  amountCents: number\n  registerId: string\n  livemode: boolean\n  /** Whether the sale has synced (its order exists). */\n  synced: boolean\n  lastEvent: string\n  updatedAtMs: number\n}\n\nexport async function reconcilePosOfflineCardEvent(\n  input: { type: string; object: any },\n  firestore?: FirebaseFirestore.Firestore,\n  now: () => number = Date.now,\n): Promise<{ hostId: string } | null> {\n  if (!input.type.startsWith('payment_intent.')) return null\n  const intent = input.object ?? {}\n  const metadata = (intent.metadata ?? {}) as Record<string, string>\n  if (metadata['kind'] !== POS_OFFLINE_CARD_INTENT_KIND) return null\n  const hostId = String(metadata['hostId'] ?? '')\n  const saleKey = String(metadata['saleKey'] ?? '')\n  if (\n    !/^[A-Za-z0-9_-]{1,128}$/.test(hostId) ||\n    !posOfflineSaleKeyIsValid(saleKey)\n  )\n    return null\n  const hostRef = (firestore ?? firebaseAdmin.app().firestore())\n    .collection('hosts')\n    .doc(hostId)\n  const synced = (\n    await hostRef.collection('posOfflineSales').doc(saleKey).get()\n  ).exists\n  const record: PosOfflineCardChargeRecord = {\n    saleKey,\n    paymentIntentId: String(intent.id ?? ''),\n    status: String(intent.status ?? ''),\n    amountCents: Number(intent.amount ?? 0),\n    registerId: String(metadata['registerId'] ?? '').slice(0, 128),\n    livemode: Boolean(intent.livemode),\n    synced,\n    lastEvent: input.type,\n    updatedAtMs: now(),\n  }\n  await hostRef\n    .collection('terminal')\n    .doc('config')\n    .collection('offlineCardCharges')\n    .doc(saleKey)\n    .set(record, { merge: true })\n  return { hostId }\n}\n\n/** The platform webhook's handler for offline card intents: claims only its own. */\nexport const posOfflineCardBillingWebhookHandler: BillingWebhookHandler =\n  async ({ type, object }) => {\n    const reconciled = await reconcilePosOfflineCardEvent({ type, object })\n    return reconciled ? { claimed: true, hostId: reconciled.hostId } : undefined\n  }\n"],"names":["firebaseAdmin","POS_OFFLINE_CARD_INTENT_KIND","posOfflineSaleKeyIsValid","reconcilePosOfflineCardEvent","input","firestore","now","Date","intent","metadata","type","startsWith","object","hostId","String","saleKey","test","hostRef","app","collection","doc","synced","get","exists","record","paymentIntentId","id","status","amountCents","Number","amount","registerId","slice","livemode","Boolean","lastEvent","updatedAtMs","set","merge","posOfflineCardBillingWebhookHandler","reconciled","claimed","undefined"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAGD,SAASA,aAAa,QAAQ,2BAA0B;AACxD,SACEC,4BAA4B,EAC5BC,wBAAwB,QACnB,mCAA+B;AAkCtC,OAAO,eAAeC,6BACpBC,KAAoC,EACpCC,SAAuC,EACvCC,MAAoBC,KAAKD,GAAG;QAGbF,eACGI,kBAEIC,kBACCA,mBAcGD,YACTA,gBACKA,gBACDC;IAtBrB,IAAI,CAACL,MAAMM,IAAI,CAACC,UAAU,CAAC,oBAAoB,OAAO;IACtD,MAAMH,UAASJ,gBAAAA,MAAMQ,MAAM,YAAZR,gBAAgB,CAAC;IAChC,MAAMK,YAAYD,mBAAAA,OAAOC,QAAQ,YAAfD,mBAAmB,CAAC;IACtC,IAAIC,QAAQ,CAAC,OAAO,KAAKR,8BAA8B,OAAO;IAC9D,MAAMY,SAASC,QAAOL,mBAAAA,QAAQ,CAAC,SAAS,YAAlBA,mBAAsB;IAC5C,MAAMM,UAAUD,QAAOL,oBAAAA,QAAQ,CAAC,UAAU,YAAnBA,oBAAuB;IAC9C,IACE,CAAC,yBAAyBO,IAAI,CAACH,WAC/B,CAACX,yBAAyBa,UAE1B,OAAO;IACT,MAAME,UAAU,CAACZ,oBAAAA,YAAaL,cAAckB,GAAG,GAAGb,SAAS,IACxDc,UAAU,CAAC,SACXC,GAAG,CAACP;IACP,MAAMQ,SAAS,AACb,CAAA,MAAMJ,QAAQE,UAAU,CAAC,mBAAmBC,GAAG,CAACL,SAASO,GAAG,EAAC,EAC7DC,MAAM;IACR,MAAMC,SAAqC;QACzCT;QACAU,iBAAiBX,QAAON,aAAAA,OAAOkB,EAAE,YAATlB,aAAa;QACrCmB,QAAQb,QAAON,iBAAAA,OAAOmB,MAAM,YAAbnB,iBAAiB;QAChCoB,aAAaC,QAAOrB,iBAAAA,OAAOsB,MAAM,YAAbtB,iBAAiB;QACrCuB,YAAYjB,QAAOL,uBAAAA,QAAQ,CAAC,aAAa,YAAtBA,uBAA0B,IAAIuB,KAAK,CAAC,GAAG;QAC1DC,UAAUC,QAAQ1B,OAAOyB,QAAQ;QACjCZ;QACAc,WAAW/B,MAAMM,IAAI;QACrB0B,aAAa9B;IACf;IACA,MAAMW,QACHE,UAAU,CAAC,YACXC,GAAG,CAAC,UACJD,UAAU,CAAC,sBACXC,GAAG,CAACL,SACJsB,GAAG,CAACb,QAAQ;QAAEc,OAAO;IAAK;IAC7B,OAAO;QAAEzB;IAAO;AAClB;AAEA,kFAAkF,GAClF,OAAO,MAAM0B,sCACX,OAAO,EAAE7B,IAAI,EAAEE,MAAM,EAAE;IACrB,MAAM4B,aAAa,MAAMrC,6BAA6B;QAAEO;QAAME;IAAO;IACrE,OAAO4B,aAAa;QAAEC,SAAS;QAAM5B,QAAQ2B,WAAW3B,MAAM;IAAC,IAAI6B;AACrE,EAAC"}
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/pos-offline-card-reconcile.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 { formatOperatorAlertAmount } from '@aglyn/aglyn/app-utils/operator-alerts'\nimport type { BillingWebhookHandler, PluginJobHostGate } from '@aglyn/aglyn/server'\nimport {\n  firebaseAdmin,\n  hostDisplayName,\n  notifyHostManagers,\n  raiseOperatorAlert,\n} from '@aglyn/tenant-data-admin'\nimport { FieldValue } from 'firebase-admin/firestore'\nimport {\n  COMMERCE_POS_OFFLINE_CARD_UNSYNCED,\n  COMMERCE_POS_OFFLINE_CARD_WRONG_ACCOUNT,\n} from '../constants/operator-alerts'\nimport {\n  POS_OFFLINE_CARD_INTENT_KIND,\n  posOfflineSaleKeyIsValid,\n} from '../model/commerce-pos-offline'\n\n/*==========================================\n * A CARD TAKEN OFFLINE, AS STRIPE REPORTS IT (AGL-4039).\n *\n * The Aglyn POS app creates the PaymentIntent of a card it takes offline, so\n * Stripe can know of a charge before the sale itself reaches the server: the\n * SDK forwards the card the moment a connection returns, and the sale syncs\n * right after, from the same device. Usually seconds apart. If the sale never\n * arrives (the device was lost or wiped between the two, or it waits for a\n * member who never signs in again), the charge must not be invisible: each\n * event on such an intent is kept on the site, by the sale's key, under the\n * site's server-only Terminal document\n * (`terminal/config/offlineCardCharges/{saleKey}`), beside whether the sale\n * has synced. The sync itself never depends on this: it reads Stripe.\n *\n * WHO SAYS \"SYNCED\". Both writers, in transactions, so neither can undo the\n * other: the sync marks the record when it creates the order, and an event\n * reads the record and the sync record together. An event that arrives after\n * the sync therefore keeps `synced`, and one that raced it retries and sees\n * it.\n *\n * NOBODY LOOKING. An intent that holds or has taken money while its sale has\n * not synced gets `alertDueAtMs`, {@link POS_OFFLINE_CARD_UNSYNCED_ALERT_MS}\n * after it was first seen. The hourly sweep ({@link scanUnsyncedOfflineCards})\n * tells the operator and the site's managers once, with time left to sync the\n * sale before Stripe's authorization lapses (about two days). It never\n * captures: without the sale there is no fee to capture with.\n *\n * Self-selecting: every other event returns `null` untouched. Registered on\n * the platform webhook from the commerce server module, beside the other\n * commerce handlers, rather than as a branch of the storefront sections. The\n * four `payment_intent.*` events it reads are in the platform destination's\n * `WEBHOOK_EVENTS` (`tools/scripts/lib/stripe-webhook-health.mjs`).\n *=========================================*/\n\n/** The subcollection, under `hosts/{hostId}/terminal/config`, and its collection-group name. */\nexport const POS_OFFLINE_CARD_CHARGES = 'offlineCardCharges'\n\n/**\n * How long an intent that holds money may wait for its sale before the sweep\n * says so: six hours, which leaves well over a day of Stripe's two-day\n * authorization to sync it, and is far past the seconds a healthy sync takes.\n */\nexport const POS_OFFLINE_CARD_UNSYNCED_ALERT_MS = 6 * 60 * 60 * 1000\n\n/** Statuses in which an intent holds money or has taken it. */\nconst HOLDS_MONEY: ReadonlySet<string> = new Set(['requires_capture', 'processing', 'succeeded'])\n\n/** Statuses an intent never leaves; an older event must not turn one back. */\nconst FINAL: ReadonlySet<string> = new Set(['succeeded', 'canceled'])\n\n/** What the site keeps about one offline card's PaymentIntent. */\nexport interface PosOfflineCardChargeRecord {\n  hostId: string\n  saleKey: string\n  paymentIntentId: string\n  status: string\n  amountCents: number\n  registerId: string\n  livemode: boolean\n  /** Whether the sale has synced (its order exists). */\n  synced: boolean\n  orderId?: string\n  syncedAtMs?: number\n  lastEvent: string\n  updatedAtMs: number\n  /** When the sweep says the sale never synced; absent once synced or told. */\n  alertDueAtMs?: number\n  alertedAtMs?: number\n  /** The capture's idempotency attempt, raised only after a definite failure. */\n  captureAttempt?: number\n}\n\n/** `hosts/{hostId}/terminal/config/offlineCardCharges/{saleKey}`. */\nexport function posOfflineCardChargeRef(\n  hostRef: FirebaseFirestore.DocumentReference,\n  saleKey: string,\n): FirebaseFirestore.DocumentReference {\n  return hostRef.collection('terminal').doc('config').collection(POS_OFFLINE_CARD_CHARGES).doc(saleKey)\n}\n\nconst validHostId = (hostId: string) => /^[A-Za-z0-9_-]{1,128}$/.test(hostId)\n\nexport async function reconcilePosOfflineCardEvent(\n  input: { type: string; object: any },\n  firestore?: FirebaseFirestore.Firestore,\n  now: () => number = Date.now,\n): Promise<{ hostId: string } | null> {\n  if (!input.type.startsWith('payment_intent.')) return null\n  const intent = input.object ?? {}\n  const metadata = (intent.metadata ?? {}) as Record<string, string>\n  if (metadata['kind'] !== POS_OFFLINE_CARD_INTENT_KIND) return null\n  const hostId = String(metadata['hostId'] ?? '')\n  const saleKey = String(metadata['saleKey'] ?? '')\n  if (!validHostId(hostId) || !posOfflineSaleKeyIsValid(saleKey)) return null\n  const db = firestore ?? firebaseAdmin.app().firestore()\n  const hostRef = db.collection('hosts').doc(hostId)\n  const chargeRef = posOfflineCardChargeRef(hostRef, saleKey)\n  const saleRef = hostRef.collection('posOfflineSales').doc(saleKey)\n  await db.runTransaction(async (transaction) => {\n    const charge = await transaction.get(chargeRef)\n    const sale = await transaction.get(saleRef)\n    const previous = (charge.exists ? charge.data() : {}) as Partial<PosOfflineCardChargeRecord>\n    const synced = previous.synced === true || sale.exists\n    const incoming = String(intent.status ?? '')\n    // Stripe does not promise event order: a late `amount_capturable_updated`\n    // must not turn a captured or canceled intent back into an authorized one.\n    const status =\n      previous.status && FINAL.has(previous.status) && !FINAL.has(incoming) ? previous.status : incoming\n    const at = now()\n    const alertDueAtMs =\n      !synced && HOLDS_MONEY.has(status) && !previous.alertedAtMs\n        ? typeof previous.alertDueAtMs === 'number'\n          ? previous.alertDueAtMs\n          : at + POS_OFFLINE_CARD_UNSYNCED_ALERT_MS\n        : null\n    transaction.set(\n      chargeRef,\n      {\n        hostId,\n        saleKey,\n        paymentIntentId: String(intent.id ?? ''),\n        status,\n        amountCents: Math.max(0, Math.round(Number(intent.amount ?? 0))),\n        registerId: String(metadata['registerId'] ?? '').slice(0, 128),\n        livemode: Boolean(intent.livemode),\n        synced,\n        lastEvent: input.type,\n        updatedAtMs: at,\n        alertDueAtMs: alertDueAtMs ?? FieldValue.delete(),\n      },\n      { merge: true },\n    )\n  })\n  return { hostId }\n}\n\n/** The platform webhook's handler for offline card intents: claims only its own. */\nexport const posOfflineCardBillingWebhookHandler: BillingWebhookHandler =\n  async ({ type, object }) => {\n    const reconciled = await reconcilePosOfflineCardEvent({ type, object })\n    return reconciled ? { claimed: true, hostId: reconciled.hostId } : undefined\n  }\n\n/*==========================================\n * THE SWEEP: AN OFFLINE CARD WHOSE SALE NEVER SYNCED.\n *=========================================*/\n\nexport interface UnsyncedOfflineCardReport {\n  hostId: string\n  saleKey: string\n  paymentIntentId: string\n  status: string\n  amountCents: number\n  registerId: string\n  /** How long ago the intent was first seen waiting, in ms. */\n  waitedMs: number\n}\n\nexport interface UnsyncedOfflineCardScan {\n  due: number\n  alerted: number\n  /** Synced, or no longer holding money, since the alert was set. */\n  cleared: number\n  skippedLocked: number\n}\n\nconst describeWait = (ms: number) => {\n  const hours = Math.max(1, Math.round(ms / (60 * 60 * 1000)))\n  return hours >= 48 ? `${Math.round(hours / 24)} days` : `${hours} hour${hours === 1 ? '' : 's'}`\n}\n\n/** Tells the operator and the site's managers about one card. Never throws. */\nexport async function reportUnsyncedOfflineCard(report: UnsyncedOfflineCardReport): Promise<void> {\n  try {\n    const host = await firebaseAdmin.app().firestore().collection('hosts').doc(report.hostId).get().catch(() => null)\n    const site = host?.exists ? hostDisplayName(host.data() as Record<string, unknown>, report.hostId) : report.hostId\n    const amount = formatOperatorAlertAmount(report.amountCents)\n    await raiseOperatorAlert(COMMERCE_POS_OFFLINE_CARD_UNSYNCED, {\n      dedupeKey: `${report.hostId}:${report.saleKey}`,\n      hostId: report.hostId,\n      context: {\n        amount,\n        paymentIntentId: report.paymentIntentId,\n        status: report.status,\n        site: `${site} (${report.hostId})`,\n        registerId: report.registerId || 'unknown',\n        age: describeWait(report.waitedMs),\n      },\n    })\n    await notifyHostManagers(report.hostId, {\n      type: 'content.order',\n      title: `A ${amount} card taken offline on {site} has no sale`,\n      body:\n        report.status === 'succeeded'\n          ? `A ${amount} card taken offline was charged, but the register never sent its sale, so there is no order for it. ` +\n            'Open the register that took it, signed in as the member who rang it, so the sale syncs.'\n          : `A ${amount} card taken offline is approved but not yet charged, because the register never sent its sale. ` +\n            'Open the register that took it, signed in as the member who rang it, so the sale syncs. ' +\n            'If it does not sync within about two days of the sale, the card is never charged.',\n      link: `/${report.hostId}/products`,\n    })\n  } catch (error) {\n    console.error('[pos-offline-card] unsynced report failed', report.hostId, report.saleKey, error)\n  }\n}\n\n/** Tells the operator a card was made out to an account that is not the store's. Never throws. */\nexport async function reportPosOfflineCardWrongAccount(input: {\n  hostId: string\n  orderId: string\n  paymentIntentId: string\n  status: string\n  amountCents: number\n  destination: string\n  expected: string\n}): Promise<void> {\n  try {\n    const host = await firebaseAdmin.app().firestore().collection('hosts').doc(input.hostId).get().catch(() => null)\n    const site = host?.exists ? hostDisplayName(host.data() as Record<string, unknown>, input.hostId) : input.hostId\n    await raiseOperatorAlert(COMMERCE_POS_OFFLINE_CARD_WRONG_ACCOUNT, {\n      dedupeKey: `${input.hostId}:${input.orderId}`,\n      hostId: input.hostId,\n      context: {\n        amount: formatOperatorAlertAmount(input.amountCents),\n        paymentIntentId: input.paymentIntentId,\n        status: input.status,\n        orderId: input.orderId,\n        site: `${site} (${input.hostId})`,\n        destination: input.destination || 'none',\n        expected: input.expected,\n      },\n    })\n  } catch (error) {\n    console.error('[pos-offline-card] wrong-account alert failed', input.hostId, input.orderId, error)\n  }\n}\n\n/**\n * The hourly sweep (registered in `server.ts`): every offline card record\n * whose alert is due. Re-checks the sale first, so a sale that synced while\n * the event was in flight clears the record and tells nobody.\n *\n * One collection-group range query on `alertDueAtMs`, which is set only on a\n * record that holds money and has not synced, so the ordinary beat reads an\n * empty result. Its COLLECTION_GROUP index is declared in\n * `cloud/firebase-firestore.indexes.json` and pinned by\n * `cron-scan-indexes.spec.ts`.\n */\nexport async function scanUnsyncedOfflineCards(\n  /** The lockdown gate, injected by the runner (AGL-2495). */\n  gate: PluginJobHostGate,\n  options: {\n    firestore?: FirebaseFirestore.Firestore\n    nowMs?: number\n    limit?: number\n    report?: (report: UnsyncedOfflineCardReport) => Promise<void>\n  } = {},\n): Promise<UnsyncedOfflineCardScan> {\n  const db = options.firestore ?? firebaseAdmin.app().firestore()\n  const nowMs = options.nowMs ?? Date.now()\n  const report = options.report ?? reportUnsyncedOfflineCard\n  const scan: UnsyncedOfflineCardScan = { due: 0, alerted: 0, cleared: 0, skippedLocked: 0 }\n  const due = await db\n    .collectionGroup(POS_OFFLINE_CARD_CHARGES)\n    .where('alertDueAtMs', '<=', nowMs)\n    .orderBy('alertDueAtMs', 'asc')\n    .limit(options.limit ?? 100)\n    .get()\n    .catch((error: unknown) => {\n      console.error('[pos-offline-card] unsynced scan failed', error)\n      return null\n    })\n  if (!due) return scan\n  for (const doc of due.docs) {\n    const record = (doc.data() ?? {}) as Partial<PosOfflineCardChargeRecord>\n    if (typeof record.alertDueAtMs !== 'number') continue\n    // `hosts/{hostId}/terminal/config/offlineCardCharges/{saleKey}`.\n    const hostId = String(record.hostId || doc.ref.parent.parent?.parent?.parent?.id || '')\n    const saleKey = String(record.saleKey || doc.id)\n    if (!validHostId(hostId) || !posOfflineSaleKeyIsValid(saleKey)) continue\n    scan.due += 1\n    // A locked site is skipped, not dropped: its record stays due and is\n    // told on the first beat after the lift.\n    if (await gate.isLocked(hostId)) {\n      scan.skippedLocked += 1\n      continue\n    }\n    const hostRef = db.collection('hosts').doc(hostId)\n    const synced = (await hostRef.collection('posOfflineSales').doc(saleKey).get()).exists\n    if (synced || !HOLDS_MONEY.has(String(record.status ?? ''))) {\n      await doc.ref.set(\n        { ...(synced ? { synced: true } : {}), alertDueAtMs: FieldValue.delete() },\n        { merge: true },\n      )\n      scan.cleared += 1\n      continue\n    }\n    await report({\n      hostId,\n      saleKey,\n      paymentIntentId: String(record.paymentIntentId ?? ''),\n      status: String(record.status ?? ''),\n      amountCents: Math.max(0, Math.round(Number(record.amountCents ?? 0))),\n      registerId: String(record.registerId ?? ''),\n      waitedMs: Math.max(0, nowMs - (record.alertDueAtMs - POS_OFFLINE_CARD_UNSYNCED_ALERT_MS)),\n    })\n    await doc.ref.set({ alertedAtMs: nowMs, alertDueAtMs: FieldValue.delete() }, { merge: true })\n    scan.alerted += 1\n  }\n  return scan\n}\n"],"names":["formatOperatorAlertAmount","firebaseAdmin","hostDisplayName","notifyHostManagers","raiseOperatorAlert","FieldValue","COMMERCE_POS_OFFLINE_CARD_UNSYNCED","COMMERCE_POS_OFFLINE_CARD_WRONG_ACCOUNT","POS_OFFLINE_CARD_INTENT_KIND","posOfflineSaleKeyIsValid","POS_OFFLINE_CARD_CHARGES","POS_OFFLINE_CARD_UNSYNCED_ALERT_MS","HOLDS_MONEY","Set","FINAL","posOfflineCardChargeRef","hostRef","saleKey","collection","doc","validHostId","hostId","test","reconcilePosOfflineCardEvent","input","firestore","now","Date","intent","metadata","type","startsWith","object","String","db","app","chargeRef","saleRef","runTransaction","transaction","charge","get","sale","previous","exists","data","synced","incoming","status","has","at","alertDueAtMs","alertedAtMs","set","paymentIntentId","id","amountCents","Math","max","round","Number","amount","registerId","slice","livemode","Boolean","lastEvent","updatedAtMs","delete","merge","posOfflineCardBillingWebhookHandler","reconciled","claimed","undefined","describeWait","ms","hours","reportUnsyncedOfflineCard","report","host","catch","site","dedupeKey","context","age","waitedMs","title","body","link","error","console","reportPosOfflineCardWrongAccount","orderId","destination","expected","scanUnsyncedOfflineCards","gate","options","nowMs","scan","due","alerted","cleared","skippedLocked","collectionGroup","where","orderBy","limit","docs","record","ref","parent","isLocked"],"mappings":"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"}

package/src/lib/server/pos-offline-sync.d.ts

@@ -85,13 +85,28 @@ export interface PosOfflineCardDeps {
         ok: false;
         error: string;
     }>;
+    /**
+     * Captures with the platform fee. A failure carries Stripe's HTTP status
+     * when Stripe answered; a request that never got an answer throws.
+     */
     capture(paymentIntentId: string, applicationFeeCents: number, idempotencyKey: string): Promise<{
         ok: true;
         intent: PosOfflineCardIntent;
     } | {
         ok: false;
         error: string;
+        status?: number;
     }>;
+    /** Tells the operator a card was made out to another account. Never throws. */
+    wrongAccount(input: {
+        hostId: string;
+        orderId: string;
+        paymentIntentId: string;
+        status: string;
+        amountCents: number;
+        destination: string;
+        expected: string;
+    }): Promise<void>;
 }
 export declare function defaultPosOfflineCardDeps(): PosOfflineCardDeps;
 export declare function defaultPosOfflineSyncDeps(): PosOfflineSyncDeps;
@@ -111,6 +126,30 @@ export declare function posInPersonTax(settings: CommerceModel.TaxSettings | und
 };
 /** The kit a register caches to sell offline. */
 export declare function buildPosOfflineKit(deps: PosOfflineSyncDeps, staff: PosOpsStaff): Promise<PosOfflineKit>;
+/**
+ * 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 declare 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 declare function posOfflineCaptureKey(hostId: string, saleKey: string, attempt: number): string;
+/** A capture Stripe refused for good: retrying the same key would replay the refusal. */
+export declare function posOfflineCaptureRefused(status: number | undefined): boolean;
 export declare function handlePosOfflineSync(deps: PosOfflineSyncDeps, req: PluginApiRequest): Promise<Outcome>;
 export declare function createPosOfflineSyncHandler(deps?: () => PosOfflineSyncDeps): PluginApiHandler;
 export declare const posOfflineSyncHandler: Aglyn.PluginApiHandler;