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

package/src/lib/server/pos-hardware-in-person.js

@@ -0,0 +1,236 @@
+/**
+ * @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 { firebaseAdmin, getOrgForHost } from "@aglyn/tenant-data-admin";
+import * as CommerceModel from "../model/index.js";
+import { isPosHardwareSkuId, normalizePosHardwareSerial } from "../model/pos-hardware.js";
+import { inPersonPosHardwareOrder, posHardwareRegisterShare } from "../model/pos-hardware-in-person.js";
+import { hardwareOrdersRef, posHardwareInPersonConfig, posHardwareInPersonOrderId } from "./pos-hardware.js";
+import { recordPosHardwareOrder } from "./pos-hardware-webhook.js";
+import { posStripeTestMode } from "./pos-stripe.js";
+/** How many marked sales one sweep records at most. */ export const IN_PERSON_SWEEP_LIMIT = 25;
+/** Statuses after which a marked sale can never be paid, so the mark is dropped. */ const NEVER_PAID = new Set([
+    'cancelled',
+    'canceled',
+    'voided',
+    'refunded',
+    'expired'
+]);
+const text = (value)=>typeof value === 'string' && value.trim() ? value.trim() : null;
+function firestore() {
+    return firebaseAdmin.app().firestore();
+}
+function registerOrderRef(hostId, orderId) {
+    return firestore().collection('hosts').doc(hostId).collection('orders').doc(orderId);
+}
+/** Where the store taxes from, and its rate there, from its own tax settings. */ async function storeTax(hostId) {
+    var _settings_get, _tax_origin, _ref, _ref1;
+    var _text, _text1;
+    const settings = await firestore().collection('hosts').doc(hostId).collection('settings').doc('store').get();
+    const tax = (_settings_get = settings.get('tax')) != null ? _settings_get : {};
+    const origin = (_tax_origin = tax.origin) != null ? _tax_origin : {};
+    const country = (_ref = (_text = text(origin.country)) == null ? void 0 : _text.toUpperCase()) != null ? _ref : null;
+    const rate = country ? CommerceModel.resolveTaxRate(tax, origin) : null;
+    return {
+        region: country ? {
+            country,
+            state: (_ref1 = (_text1 = text(origin.state)) == null ? void 0 : _text1.toUpperCase()) != null ? _ref1 : null,
+            postalCode: null
+        } : null,
+        ratePct: rate && Number.isFinite(rate.pct) ? rate.pct : null
+    };
+}
+/** The store owner's connected Stripe account, where the store's card money goes. */ async function storeStripeAccount(hostId) {
+    var _owner_org;
+    const owner = await getOrgForHost(hostId).catch(()=>null);
+    const ownerUid = text(owner == null ? void 0 : (_owner_org = owner.org) == null ? void 0 : _owner_org.ownerUid);
+    if (!ownerUid) return null;
+    const profile = await firestore().collection('profiles').doc(ownerUid).get();
+    return text(profile.get('stripeAccountId'));
+}
+/**
+ * Records the hardware order of one register sale on the seller store, once.
+ * Never throws for a sale that is not one: it says why it did nothing.
+ */ export async function recordInPersonPosHardwareSale(hostId, registerOrderId, options = {}) {
+    var _ref, _ref1, _ref2, _ref3, _order_paidAtMs, _text, _ref4, _order_currency;
+    var _order_totals, _order_totals1, _payments_find, _text1, _hardwareOrder_attachment, _hardwareOrder_attachment1;
+    const config = options.config === undefined ? posHardwareInPersonConfig() : options.config;
+    if (!config) return {
+        outcome: 'off'
+    };
+    if (hostId !== config.sellerHostId) return {
+        outcome: 'not-seller'
+    };
+    const orderRef = registerOrderRef(hostId, registerOrderId);
+    const snapshot = await orderRef.get();
+    if (!snapshot.exists) return {
+        outcome: 'missing'
+    };
+    const order = snapshot.data();
+    if (order.status !== 'paid') return {
+        outcome: 'not-paid'
+    };
+    const lineItems = Array.isArray(order.lineItems) ? order.lineItems : [];
+    const productIds = [
+        ...new Set(lineItems.map((line)=>{
+            var _line_productId;
+            return String((_line_productId = line.productId) != null ? _line_productId : '');
+        }).filter(Boolean))
+    ];
+    const products = new Map((await Promise.all(productIds.map((id)=>firestore().collection('hosts').doc(hostId).collection('products').doc(id).get()))).map((doc)=>[
+            String(doc.id),
+            doc.exists ? doc.data() : null
+        ]));
+    const lines = lineItems.map((line)=>{
+        var _products_get;
+        const sku = (_products_get = products.get(String(line.productId))) == null ? void 0 : _products_get.hardwareSku;
+        return {
+            sku: isPosHardwareSkuId(sku) ? sku : null,
+            quantity: Number(line.quantity),
+            unitAmountCents: Number(line.unitAmountCents)
+        };
+    });
+    const share = posHardwareRegisterShare({
+        lines,
+        discountCents: Number((_ref = (_order_totals = order.totals) == null ? void 0 : _order_totals.discountCents) != null ? _ref : 0),
+        taxCents: Number((_ref1 = (_order_totals1 = order.totals) == null ? void 0 : _order_totals1.taxCents) != null ? _ref1 : 0)
+    });
+    if (!share) {
+        // Marked when it was rung, but no line is hardware now: nothing to record.
+        if (order.hardwareSalePending) {
+            await orderRef.set({
+                hardwareSalePending: firebaseAdmin.firestore.FieldValue.delete()
+            }, {
+                merge: true
+            });
+        }
+        return {
+            outcome: 'no-hardware'
+        };
+    }
+    const orderId = posHardwareInPersonOrderId(hostId, registerOrderId);
+    const payments = CommerceModel.orderPayments(order).filter((payment)=>payment.status === 'succeeded');
+    const livemodes = payments.map((payment)=>payment.livemode).filter((mode)=>typeof mode === 'boolean');
+    const [tax, stripeAccountId] = await Promise.all([
+        storeTax(hostId),
+        storeStripeAccount(hostId)
+    ]);
+    const paidAtMs = Number((_ref2 = (_ref3 = (_order_paidAtMs = order.paidAtMs) != null ? _order_paidAtMs : order.createdAtMs) != null ? _ref3 : options.now) != null ? _ref2 : Date.now());
+    const hardwareOrder = inPersonPosHardwareOrder({
+        sellerHostId: config.sellerHostId,
+        sellerOrgId: config.sellerOrgId,
+        registerOrderId,
+        number: Number.isFinite(Number(order.number)) ? Number(order.number) : null,
+        registerId: text(order.registerId),
+        kiosk: order.posSource === 'kiosk',
+        offline: options.offline === true || Boolean(order.offline),
+        share,
+        paidAtMs,
+        tenders: payments.map((payment)=>payment.method),
+        paymentLinkSessionId: (_text = text((_payments_find = payments.find((payment)=>payment.checkoutSessionId)) == null ? void 0 : _payments_find.checkoutSessionId)) != null ? _text : text(order.checkoutSessionId),
+        receiptEmail: (_ref4 = (_text1 = text(order.customerEmail)) == null ? void 0 : _text1.toLowerCase()) != null ? _ref4 : null,
+        buyer: order.hardwareBuyer,
+        termsAcceptance: order.hardwareTermsAcceptance,
+        serials: (Array.isArray(order.hardwareSerials) ? order.hardwareSerials : []).map(normalizePosHardwareSerial).filter(Boolean),
+        taxRegion: tax.region,
+        ratePct: tax.ratePct,
+        stripeAccountId,
+        // A card payment says which mode it was in; a cash sale takes the
+        // deployment's, so a test deployment's booth is never a real sale.
+        livemode: livemodes.length ? livemodes.every(Boolean) : !posStripeTestMode(),
+        currency: String((_order_currency = order.currency) != null ? _order_currency : 'usd').toLowerCase()
+    });
+    const { created } = await recordPosHardwareOrder(orderId, hardwareOrder);
+    // The mark comes off once the order exists, by this call or an earlier one.
+    await orderRef.set({
+        hardwareOrderId: orderId,
+        hardwareSalePending: firebaseAdmin.firestore.FieldValue.delete()
+    }, {
+        merge: true
+    });
+    // A buyer with no account, named at the register while the sale was open,
+    // is invited to sign up now that there is an order to point them at.
+    if (created && ((_hardwareOrder_attachment = hardwareOrder.attachment) == null ? void 0 : _hardwareOrder_attachment.state) === 'pending' && hardwareOrder.attachment.email) {
+        await (await import("./pos-hardware-attach.js")).invitePendingBuyer(orderId, hardwareOrder.orgId, hardwareOrder);
+    }
+    return {
+        outcome: created ? 'recorded' : 'already',
+        orderId,
+        orgId: hardwareOrder.orgId,
+        pending: ((_hardwareOrder_attachment1 = hardwareOrder.attachment) == null ? void 0 : _hardwareOrder_attachment1.state) === 'pending'
+    };
+}
+/**
+ * Records every paid sale on the seller store that is still marked, at most
+ * {@link IN_PERSON_SWEEP_LIMIT} a time, and drops the mark from a sale that
+ * can no longer be paid. Never throws: a sale it cannot record stays marked
+ * for the next sweep.
+ */ export async function sweepInPersonPosHardwareSales(config = posHardwareInPersonConfig()) {
+    if (!config) return {
+        recorded: 0,
+        failed: 0
+    };
+    const marked = await firestore().collection('hosts').doc(config.sellerHostId).collection('orders').where('hardwareSalePending', '==', true).limit(IN_PERSON_SWEEP_LIMIT).get();
+    let recorded = 0;
+    let failed = 0;
+    for (const doc of marked.docs){
+        var _doc_get;
+        const status = String((_doc_get = doc.get('status')) != null ? _doc_get : '');
+        try {
+            if (NEVER_PAID.has(status)) {
+                await doc.ref.set({
+                    hardwareSalePending: firebaseAdmin.firestore.FieldValue.delete()
+                }, {
+                    merge: true
+                });
+                continue;
+            }
+            if (status !== 'paid') continue;
+            const outcome = await recordInPersonPosHardwareSale(config.sellerHostId, String(doc.id), {
+                config
+            });
+            if (outcome.outcome === 'recorded') recorded += 1;
+        } catch (error) {
+            failed += 1;
+            console.error('[pos-hardware-in-person] a marked sale could not be recorded', doc.id, error);
+        }
+    }
+    return {
+        recorded,
+        failed
+    };
+}
+/** The "To attach" list: the selling workspace's pending in-person orders, newest first. */ export async function pendingInPersonPosHardwareOrders(config, limit = 50) {
+    const snapshot = await hardwareOrdersRef(config.sellerOrgId).where('attachment.state', '==', 'pending').orderBy('createdAtMs', 'desc').limit(limit).get();
+    return snapshot.docs.map((doc)=>({
+            id: String(doc.id),
+            order: doc.data()
+        }));
+}
+/**
+ * What the completion listener runs for a sale on the seller store. Never
+ * throws into a sale: a failure is logged and the sale stays marked for the
+ * sweep.
+ */ export async function recordCompletedSaleHardware(event) {
+    try {
+        await recordInPersonPosHardwareSale(event.hostId, event.orderId, {
+            offline: event.offline === true
+        });
+    } catch (error) {
+        console.error('[pos-hardware-in-person] sale not recorded; the sweep will', event.orderId, error);
+    }
+}
+
+//# sourceMappingURL=pos-hardware-in-person.js.map

package/src/lib/server/pos-hardware-in-person.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/pos-hardware-in-person.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 { firebaseAdmin, getOrgForHost } from '@aglyn/tenant-data-admin'\nimport * as CommerceModel from '../model'\nimport {\n  isPosHardwareSkuId,\n  normalizePosHardwareSerial,\n  type PosHardwareInPersonConfig,\n  type PosHardwareOrder,\n  type PosHardwareTaxRegion,\n} from '../model/pos-hardware'\nimport {\n  inPersonPosHardwareOrder,\n  posHardwareRegisterShare,\n  type PosHardwareRegisterLine,\n} from '../model/pos-hardware-in-person'\nimport { hardwareOrdersRef, posHardwareInPersonConfig, posHardwareInPersonOrderId } from './pos-hardware'\nimport { recordPosHardwareOrder } from './pos-hardware-webhook'\nimport { posStripeTestMode } from './pos-stripe'\n\n/*==========================================\n * RECORDING A REGISTER SALE OF HARDWARE (AGL-4038).\n *\n * The platform's own store sells a card reader at its register; once the\n * sale is paid this writes the hardware order it becomes — attached to the\n * buyer's workspace when a register user attached one, PENDING on the\n * selling workspace's \"To attach\" list otherwise — and its retained sale\n * record, through the shop's own recorder.\n *\n * ONE SALE IS ONE ORDER. The order's id is derived from the register sale\n * (`posHardwareInPersonOrderId`) and the recorder writes it once by that id,\n * so the completion listener, a replayed webhook, an offline sync and the\n * sweep below can all reach the same sale and only the first writes.\n *\n * NOTHING IS LOST TO A FAILED LISTENER. Listeners on a completed sale are\n * logged and swallowed (the money is already taken), so the sale is marked\n * `hardwareSalePending` when it is written (`pos-hardware-sale-fields.ts`)\n * and the mark is cleared only once the order exists. The sweep records\n * every paid sale still marked, each time the To attach list is read.\n *=========================================*/\n\nexport type InPersonRecordOutcome =\n  | { outcome: 'off' | 'not-seller' | 'missing' | 'not-paid' | 'no-hardware' }\n  | { outcome: 'recorded' | 'already'; orderId: string; orgId: string; pending: boolean }\n\n/** How many marked sales one sweep records at most. */\nexport const IN_PERSON_SWEEP_LIMIT = 25\n\n/** Statuses after which a marked sale can never be paid, so the mark is dropped. */\nconst NEVER_PAID = new Set(['cancelled', 'canceled', 'voided', 'refunded', 'expired'])\n\nconst text = (value: unknown): string | null =>\n  typeof value === 'string' && value.trim() ? value.trim() : null\n\nfunction firestore() {\n  return firebaseAdmin.app().firestore()\n}\n\nfunction registerOrderRef(hostId: string, orderId: string) {\n  return firestore().collection('hosts').doc(hostId).collection('orders').doc(orderId)\n}\n\n/** Where the store taxes from, and its rate there, from its own tax settings. */\nasync function storeTax(hostId: string): Promise<{ region: PosHardwareTaxRegion | null; ratePct: number | null }> {\n  const settings = await firestore().collection('hosts').doc(hostId).collection('settings').doc('store').get()\n  const tax = (settings.get('tax') ?? {}) as CommerceModel.TaxSettings\n  const origin = tax.origin ?? {}\n  const country = text(origin.country)?.toUpperCase() ?? null\n  const rate = country ? CommerceModel.resolveTaxRate(tax, origin) : null\n  return {\n    region: country ? { country, state: text(origin.state)?.toUpperCase() ?? null, postalCode: null } : null,\n    ratePct: rate && Number.isFinite(rate.pct) ? rate.pct : null,\n  }\n}\n\n/** The store owner's connected Stripe account, where the store's card money goes. */\nasync function storeStripeAccount(hostId: string): Promise<string | null> {\n  const owner = await getOrgForHost(hostId).catch(() => null)\n  const ownerUid = text((owner?.org as { ownerUid?: unknown } | undefined)?.ownerUid)\n  if (!ownerUid) return null\n  const profile = await firestore().collection('profiles').doc(ownerUid).get()\n  return text(profile.get('stripeAccountId'))\n}\n\n/**\n * Records the hardware order of one register sale on the seller store, once.\n * Never throws for a sale that is not one: it says why it did nothing.\n */\nexport async function recordInPersonPosHardwareSale(\n  hostId: string,\n  registerOrderId: string,\n  options: { offline?: boolean; config?: PosHardwareInPersonConfig | null; now?: number } = {},\n): Promise<InPersonRecordOutcome> {\n  const config = options.config === undefined ? posHardwareInPersonConfig() : options.config\n  if (!config) return { outcome: 'off' }\n  if (hostId !== config.sellerHostId) return { outcome: 'not-seller' }\n  const orderRef = registerOrderRef(hostId, registerOrderId)\n  const snapshot = await orderRef.get()\n  if (!snapshot.exists) return { outcome: 'missing' }\n  const order = snapshot.data() as CommerceModel.HostOrder & {\n    paidAtMs?: number\n    checkoutSessionId?: string\n    customerEmail?: string | null\n  }\n  if (order.status !== 'paid') return { outcome: 'not-paid' }\n\n  const lineItems = Array.isArray(order.lineItems) ? order.lineItems : []\n  const productIds = [...new Set(lineItems.map((line) => String(line.productId ?? '')).filter(Boolean))]\n  const products = new Map(\n    (\n      await Promise.all(\n        productIds.map((id) => firestore().collection('hosts').doc(hostId).collection('products').doc(id).get()),\n      )\n    ).map((doc: any) => [String(doc.id), doc.exists ? (doc.data() as CommerceModel.HostProduct) : null]),\n  )\n  const lines: PosHardwareRegisterLine[] = lineItems.map((line) => {\n    const sku = products.get(String(line.productId))?.hardwareSku\n    return {\n      sku: isPosHardwareSkuId(sku) ? sku : null,\n      quantity: Number(line.quantity),\n      unitAmountCents: Number(line.unitAmountCents),\n    }\n  })\n  const share = posHardwareRegisterShare({\n    lines,\n    discountCents: Number(order.totals?.discountCents ?? 0),\n    taxCents: Number(order.totals?.taxCents ?? 0),\n  })\n  if (!share) {\n    // Marked when it was rung, but no line is hardware now: nothing to record.\n    if (order.hardwareSalePending) {\n      await orderRef.set({ hardwareSalePending: firebaseAdmin.firestore.FieldValue.delete() }, { merge: true })\n    }\n    return { outcome: 'no-hardware' }\n  }\n\n  const orderId = posHardwareInPersonOrderId(hostId, registerOrderId)\n  const payments = CommerceModel.orderPayments(order).filter((payment) => payment.status === 'succeeded')\n  const livemodes = payments.map((payment) => payment.livemode).filter((mode): mode is boolean => typeof mode === 'boolean')\n  const [tax, stripeAccountId] = await Promise.all([storeTax(hostId), storeStripeAccount(hostId)])\n  const paidAtMs = Number(order.paidAtMs ?? order.createdAtMs ?? options.now ?? Date.now())\n  const hardwareOrder: PosHardwareOrder = inPersonPosHardwareOrder({\n    sellerHostId: config.sellerHostId,\n    sellerOrgId: config.sellerOrgId,\n    registerOrderId,\n    number: Number.isFinite(Number(order.number)) ? Number(order.number) : null,\n    registerId: text(order.registerId),\n    kiosk: order.posSource === 'kiosk',\n    offline: options.offline === true || Boolean((order as { offline?: unknown }).offline),\n    share,\n    paidAtMs,\n    tenders: payments.map((payment) => payment.method),\n    paymentLinkSessionId:\n      text(payments.find((payment) => payment.checkoutSessionId)?.checkoutSessionId) ?? text(order.checkoutSessionId),\n    receiptEmail: text(order.customerEmail)?.toLowerCase() ?? null,\n    buyer: order.hardwareBuyer,\n    termsAcceptance: order.hardwareTermsAcceptance,\n    serials: (Array.isArray(order.hardwareSerials) ? order.hardwareSerials : [])\n      .map(normalizePosHardwareSerial)\n      .filter(Boolean),\n    taxRegion: tax.region,\n    ratePct: tax.ratePct,\n    stripeAccountId,\n    // A card payment says which mode it was in; a cash sale takes the\n    // deployment's, so a test deployment's booth is never a real sale.\n    livemode: livemodes.length ? livemodes.every(Boolean) : !posStripeTestMode(),\n    currency: String((order as { currency?: unknown }).currency ?? 'usd').toLowerCase(),\n  })\n\n  const { created } = await recordPosHardwareOrder(orderId, hardwareOrder)\n  // The mark comes off once the order exists, by this call or an earlier one.\n  await orderRef.set(\n    { hardwareOrderId: orderId, hardwareSalePending: firebaseAdmin.firestore.FieldValue.delete() },\n    { merge: true },\n  )\n  // A buyer with no account, named at the register while the sale was open,\n  // is invited to sign up now that there is an order to point them at.\n  if (created && hardwareOrder.attachment?.state === 'pending' && hardwareOrder.attachment.email) {\n    await (await import('./pos-hardware-attach')).invitePendingBuyer(orderId, hardwareOrder.orgId, hardwareOrder)\n  }\n  return {\n    outcome: created ? 'recorded' : 'already',\n    orderId,\n    orgId: hardwareOrder.orgId,\n    pending: hardwareOrder.attachment?.state === 'pending',\n  }\n}\n\n/**\n * Records every paid sale on the seller store that is still marked, at most\n * {@link IN_PERSON_SWEEP_LIMIT} a time, and drops the mark from a sale that\n * can no longer be paid. Never throws: a sale it cannot record stays marked\n * for the next sweep.\n */\nexport async function sweepInPersonPosHardwareSales(\n  config: PosHardwareInPersonConfig | null = posHardwareInPersonConfig(),\n): Promise<{ recorded: number; failed: number }> {\n  if (!config) return { recorded: 0, failed: 0 }\n  const marked = await firestore()\n    .collection('hosts')\n    .doc(config.sellerHostId)\n    .collection('orders')\n    .where('hardwareSalePending', '==', true)\n    .limit(IN_PERSON_SWEEP_LIMIT)\n    .get()\n  let recorded = 0\n  let failed = 0\n  for (const doc of marked.docs as Array<{ id: string; ref: any; get: (field: string) => unknown }>) {\n    const status = String(doc.get('status') ?? '')\n    try {\n      if (NEVER_PAID.has(status)) {\n        await doc.ref.set({ hardwareSalePending: firebaseAdmin.firestore.FieldValue.delete() }, { merge: true })\n        continue\n      }\n      if (status !== 'paid') continue\n      const outcome = await recordInPersonPosHardwareSale(config.sellerHostId, String(doc.id), { config })\n      if (outcome.outcome === 'recorded') recorded += 1\n    } catch (error) {\n      failed += 1\n      console.error('[pos-hardware-in-person] a marked sale could not be recorded', doc.id, error)\n    }\n  }\n  return { recorded, failed }\n}\n\n/** The \"To attach\" list: the selling workspace's pending in-person orders, newest first. */\nexport async function pendingInPersonPosHardwareOrders(\n  config: PosHardwareInPersonConfig,\n  limit = 50,\n): Promise<Array<{ id: string; order: PosHardwareOrder }>> {\n  const snapshot = await hardwareOrdersRef(config.sellerOrgId)\n    .where('attachment.state', '==', 'pending')\n    .orderBy('createdAtMs', 'desc')\n    .limit(limit)\n    .get()\n  return snapshot.docs.map((doc: any) => ({ id: String(doc.id), order: doc.data() as PosHardwareOrder }))\n}\n\n/**\n * What the completion listener runs for a sale on the seller store. Never\n * throws into a sale: a failure is logged and the sale stays marked for the\n * sweep.\n */\nexport async function recordCompletedSaleHardware(event: {\n  hostId: string\n  orderId: string\n  offline?: boolean\n}): Promise<void> {\n  try {\n    await recordInPersonPosHardwareSale(event.hostId, event.orderId, { offline: event.offline === true })\n  } catch (error) {\n    console.error('[pos-hardware-in-person] sale not recorded; the sweep will', event.orderId, error)\n  }\n}\n"],"names":["firebaseAdmin","getOrgForHost","CommerceModel","isPosHardwareSkuId","normalizePosHardwareSerial","inPersonPosHardwareOrder","posHardwareRegisterShare","hardwareOrdersRef","posHardwareInPersonConfig","posHardwareInPersonOrderId","recordPosHardwareOrder","posStripeTestMode","IN_PERSON_SWEEP_LIMIT","NEVER_PAID","Set","text","value","trim","firestore","app","registerOrderRef","hostId","orderId","collection","doc","storeTax","settings","tax","get","origin","country","toUpperCase","rate","resolveTaxRate","region","state","postalCode","ratePct","Number","isFinite","pct","storeStripeAccount","owner","catch","ownerUid","org","profile","recordInPersonPosHardwareSale","registerOrderId","options","order","payments","hardwareOrder","config","undefined","outcome","sellerHostId","orderRef","snapshot","exists","data","status","lineItems","Array","isArray","productIds","map","line","String","productId","filter","Boolean","products","Map","Promise","all","id","lines","sku","hardwareSku","quantity","unitAmountCents","share","discountCents","totals","taxCents","hardwareSalePending","set","FieldValue","delete","merge","orderPayments","payment","livemodes","livemode","mode","stripeAccountId","paidAtMs","createdAtMs","now","Date","sellerOrgId","number","registerId","kiosk","posSource","offline","tenders","method","paymentLinkSessionId","find","checkoutSessionId","receiptEmail","customerEmail","toLowerCase","buyer","hardwareBuyer","termsAcceptance","hardwareTermsAcceptance","serials","hardwareSerials","taxRegion","length","every","currency","created","hardwareOrderId","attachment","email","invitePendingBuyer","orgId","pending","sweepInPersonPosHardwareSales","recorded","failed","marked","where","limit","docs","has","ref","error","console","pendingInPersonPosHardwareOrders","orderBy","recordCompletedSaleHardware","event"],"mappings":"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"}

package/src/lib/server/pos-hardware-notify.d.ts

@@ -15,13 +15,51 @@
  * limitations under the License.
  */
 import { POS_HARDWARE_EMAIL_KEYS } from '@aglyn/shared-util-email';
-import { type PosHardwareOrder } from '../model/pos-hardware';
+import { type PosHardwareCancelReason, type PosHardwareOrder } from '../model/pos-hardware';
 export type PosHardwareEmailKind = keyof typeof POS_HARDWARE_EMAIL_KEYS;
 /** The merge values for one order's emails. Exported for the render spec. */
 export declare function posHardwareEmailMerge(orderId: string, order: PosHardwareOrder, names: {
     site: string;
     org: string;
 }): Promise<Record<string, string>>;
-export declare function sendPosHardwareEmail(kind: PosHardwareEmailKind, orderId: string, order: PosHardwareOrder): Promise<void>;
+/** What became of one email. */
+export type PosHardwareEmailOutcome = 
+/** Sent. */
+'sent'
+/** Nobody to send it to: no address, suppressed, or the account is banned. */
+ | 'skipped'
+/** The send failed, and may be tried again. */
+ | 'failed';
+export declare function sendPosHardwareEmail(kind: PosHardwareEmailKind, orderId: string, order: PosHardwareOrder): Promise<PosHardwareEmailOutcome>;
+/**
+ * Sends one email for an order ONCE, under `key` (the kind by default; one
+ * per refund for a refund in parts). The claim is a field on the order,
+ * `buyerEmails.{key}`, taken in a transaction before the send, so the staff
+ * page and a closure, a retried press or two staff at once, send it once
+ * between them. A send that failed can be claimed again; one that found
+ * nobody to send to is not tried again. Never throws.
+ */
+export declare function sendPosHardwareEmailOnce(kind: PosHardwareEmailKind, orderId: string, order: PosHardwareOrder, key?: string): Promise<PosHardwareEmailOutcome | 'already'>;
+/**
+ * The invitation to sign up (AGL-4038), for someone who bought a card reader
+ * in person at the platform's own store with no account yet: create the
+ * account with this address and the order joins their workspace on its own.
+ * Sent in the selling workspace's brand, which is the platform's. Never
+ * throws; the caller has already claimed the send.
+ */
+/** The invitation's merge values. Exported for the render spec. */
+export declare function posHardwareInviteMerge(orderId: string, order: PosHardwareOrder): Record<string, string>;
+export declare function sendPosHardwareInvite(orderId: string, order: PosHardwareOrder): Promise<void>;
+/**
+ * A closure canceled an order staff had already placed with Stripe: the
+ * merchant is refunded, and Stripe will still ship it unless someone cancels
+ * it there. Once per order.
+ */
+export declare function raisePosHardwareCanceledAfterOrderingAlert(orderId: string, order: PosHardwareOrder, reason: PosHardwareCancelReason): Promise<void>;
+/**
+ * Stripe refused a closure's refund, and the closure went ahead without it.
+ * Carries the payment to refund by hand, never the buyer.
+ */
+export declare function raisePosHardwareRefundFailedAlert(orderId: string, order: PosHardwareOrder, reason: PosHardwareCancelReason, error: string): Promise<void>;
 /** "New hardware order", once per order. */
 export declare function raisePosHardwareOrderAlert(orderId: string, order: PosHardwareOrder): Promise<void>;

package/src/lib/server/pos-hardware-notify.js

@@ -17,13 +17,14 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  */ import { formatOperatorAlertAmount } from "@aglyn/aglyn/app-utils/operator-alerts";
 import { isAccountBanLockdownReason, normalizeOrgLockdown } from "@aglyn/aglyn/app-utils/lockdown";
 import { POS_HARDWARE_EMAIL_KEYS, sendEmail } from "@aglyn/shared-util-email";
+import { platformConsoleOrigin } from "@aglyn/aglyn/app-utils/platform-brand";
 import { firebaseAdmin, hostDisplayName, meterPlatformEmail, raiseOperatorAlert } from "@aglyn/tenant-data-admin";
 import { filterSuppressedEmails } from "@aglyn/tenant-data-admin/server/email-suppression";
 import { orgSystemEmailBrand, renderSystemEmailContent } from "@aglyn/tenant-data-admin/server/render-system-email";
-import { COMMERCE_POS_HARDWARE_ORDER } from "../constants/operator-alerts.js";
+import { COMMERCE_POS_HARDWARE_CANCELED_AFTER_ORDERING, COMMERCE_POS_HARDWARE_ORDER, COMMERCE_POS_HARDWARE_REFUND_FAILED } from "../constants/operator-alerts.js";
 import { carrierLabelFor } from "../model/tracking-url.js";
 import { formatPosHardwareCents, POS_HARDWARE_ANCHOR } from "../model/pos-hardware.js";
-import { posHardwareOrderNumber, posSettingsUrl } from "./pos-hardware.js";
+import { hardwareOrdersRef, posHardwareOrderNumber, posSettingsUrl } from "./pos-hardware.js";
 /** The lines as the emails list them, one per item. */ function itemsText(order) {
     var _order_lines;
     return ((_order_lines = order.lines) != null ? _order_lines : []).map((line)=>`${line.name} × ${line.quantity}`).join('\n');
@@ -55,18 +56,38 @@ async function siteAndOrgNames(order) {
     const lock = normalizeOrgLockdown(org == null ? void 0 : org.data());
     return {
         site: (host == null ? void 0 : host.exists) ? hostDisplayName(host.data(), order.hostId) : 'your site',
-        org: String((_ref = org == null ? void 0 : org.get('name')) != null ? _ref : '').trim() || 'your workspace',
+        org: String((_ref = org == null ? void 0 : org.get('name')) != null ? _ref : '').trim() || UNNAMED_WORKSPACE,
         ban: Boolean(lock && isAccountBanLockdownReason(lock.reason))
     };
 }
 /** The fallback subject and first line, when no design renders. */ const FALLBACK = {
     received: (number)=>`We have your card reader order ${number}`,
     shipped: (number)=>`Your card reader order ${number} has shipped`,
-    delivered: (number)=>`Your card reader order ${number} was delivered`
+    delivered: (number)=>`Your card reader order ${number} was delivered`,
+    canceled: (number)=>`Your card reader order ${number} was canceled and refunded`,
+    refunded: (number)=>`Your refund for card reader order ${number}`,
+    invited: (number)=>`Your card reader order ${number} is waiting for your account`,
+    returnRefunded: (number)=>`We refunded your returned card reader order ${number}`
 };
+/** The fallback a workspace with no name gets in a sentence. */ const UNNAMED_WORKSPACE = 'your workspace';
+/**
+ * Who canceled the order and why, as the email's first sentence; the
+ * template goes on "It had not shipped yet, so we refunded …".
+ */ function cancelReasonText(reason, org) {
+    if (reason === 'workspace-closed') {
+        return org && org !== UNNAMED_WORKSPACE ? `We canceled your order because the ${org} workspace was deleted.` : 'We canceled your order because your workspace was deleted.';
+    }
+    if (reason === 'account-closed') return 'We canceled your order because the account that placed it was closed.';
+    return 'Our team canceled your order.';
+}
+/** Why, for staff: the closure that canceled it, never who the buyer was. */ function staffReasonText(reason, orgId) {
+    if (reason === 'workspace-closed') return `its workspace ${orgId} was deleted`;
+    if (reason === 'account-closed') return 'the account that placed it was closed';
+    return 'staff canceled it';
+}
 /** The merge values for one order's emails. Exported for the render spec. */ export async function posHardwareEmailMerge(orderId, order, names) {
-    var _order_totalCents, _ref, _ref1, _ref2;
-    var _order_shipping, _order_tracking, _order_tracking1, _order_tracking2;
+    var _order_totalCents, _ref, _ref1, _ref2, _ref3, _order_refundedCents, _ref4, _ref5, _ref6, _order_refunds, _order_totalCents1, _order_refundedCents1;
+    var _order_shipping, _order_tracking, _order_tracking1, _order_tracking2, _slice_;
     const base = await posSettingsUrl(order.hostId);
     const [path] = base.split('#');
     const ordersUrl = `${path}#${POS_HARDWARE_ANCHOR}`;
@@ -83,27 +104,40 @@ async function siteAndOrgNames(order) {
         // An unknown carrier has no tracker to link; the card shows the number.
         'order.trackingUrl': (_ref2 = (_order_tracking2 = order.tracking) == null ? void 0 : _order_tracking2.url) != null ? _ref2 : ordersUrl,
         'order.ordersUrl': ordersUrl,
-        'order.setupUrl': `${path}#pos-devices`
+        'order.setupUrl': `${path}#pos-devices`,
+        // What Stripe reported refunding, or the whole charge where it has not.
+        'order.refunded': formatPosHardwareCents((_ref3 = (_order_refundedCents = order.refundedCents) != null ? _order_refundedCents : order.totalCents) != null ? _ref3 : 0),
+        // This refund alone, for an order refunded in parts; the whole of it otherwise.
+        'order.refundedNow': formatPosHardwareCents((_ref4 = (_ref5 = (_ref6 = (_slice_ = ((_order_refunds = order.refunds) != null ? _order_refunds : []).slice(-1)[0]) == null ? void 0 : _slice_.cents) != null ? _ref6 : order.refundedCents) != null ? _ref5 : order.totalCents) != null ? _ref4 : 0),
+        'order.cancelReason': cancelReasonText(order.cancelReason, names.org),
+        // What a return kept back: the original shipping and any restocking fee.
+        'order.kept': formatPosHardwareCents(Math.max(0, ((_order_totalCents1 = order.totalCents) != null ? _order_totalCents1 : 0) - ((_order_refundedCents1 = order.refundedCents) != null ? _order_refundedCents1 : 0)))
     };
 }
 export async function sendPosHardwareEmail(kind, orderId, order) {
     try {
-        var _order_contactEmail;
+        var _order_contactEmail, _ref;
+        var _order_posSale;
         const to = String((_order_contactEmail = order.contactEmail) != null ? _order_contactEmail : '').trim();
-        if (!to) return;
+        if (!to) return 'skipped';
         const names = await siteAndOrgNames(order);
         // A ban is a ban (AGL-3420): after its notice the account is sent nothing.
-        if (names.ban) return;
+        if (names.ban) return 'skipped';
         const [recipient] = await filterSuppressedEmails([
             to
         ]);
-        if (!recipient) return;
+        if (!recipient) return 'skipped';
         const merge = await posHardwareEmailMerge(orderId, order, names);
         const subject = FALLBACK[kind](merge['order.number']);
-        const brand = await orgSystemEmailBrand(order.orgId);
+        // A refund in person is in the selling workspace's brand, as its
+        // invitation is; the rest in the buyer's.
+        const brand = await orgSystemEmailBrand(kind === 'refunded' ? (_ref = (_order_posSale = order.posSale) == null ? void 0 : _order_posSale.orgId) != null ? _ref : order.orgId : order.orgId);
+        // A canceled order's workspace may be gone, so its fallback names the
+        // refund rather than linking a card that no longer opens.
+        const last = kind === 'canceled' ? `Refunded: ${merge['order.refunded']}` : kind === 'refunded' ? `Refunded now: ${merge['order.refundedNow']}` : merge['order.ordersUrl'];
         const content = await renderSystemEmailContent(POS_HARDWARE_EMAIL_KEYS[kind], merge, brand, {
             subject,
-            text: `${subject}\n\n${merge['order.items']}\n\n${merge['order.ordersUrl']}`
+            text: `${subject}\n\n${merge['order.items']}\n\n${last}`
         });
         const result = await sendEmail(_extends({
             to: recipient
@@ -112,9 +146,156 @@ export async function sendPosHardwareEmail(kind, orderId, order) {
         } : {}, {
             context: POS_HARDWARE_EMAIL_KEYS[kind]
         }));
-        if (result.sent) await meterPlatformEmail(1);
+        if (!result.sent) return 'failed';
+        await meterPlatformEmail(1);
+        return 'sent';
     } catch (error) {
         console.error('[pos-hardware] email failed', kind, orderId, error);
+        return 'failed';
+    }
+}
+/** How long a claimed send that never finished holds the next one back. */ const EMAIL_CLAIM_STALE_MS = 10 * 60 * 1000;
+/**
+ * Sends one email for an order ONCE, under `key` (the kind by default; one
+ * per refund for a refund in parts). The claim is a field on the order,
+ * `buyerEmails.{key}`, taken in a transaction before the send, so the staff
+ * page and a closure, a retried press or two staff at once, send it once
+ * between them. A send that failed can be claimed again; one that found
+ * nobody to send to is not tried again. Never throws.
+ */ export async function sendPosHardwareEmailOnce(kind, orderId, order, key = kind) {
+    try {
+        const firestore = firebaseAdmin.app().firestore();
+        const ref = hardwareOrdersRef(order.orgId).doc(orderId);
+        const claimed = await firestore.runTransaction(async (transaction)=>{
+            var _ref, _held_atMs;
+            var _snapshot_data;
+            const snapshot = await transaction.get(ref);
+            if (!snapshot.exists) return false;
+            const held = ((_ref = (_snapshot_data = snapshot.data()) == null ? void 0 : _snapshot_data.buyerEmails) != null ? _ref : {})[key];
+            const now = Date.now();
+            if ((held == null ? void 0 : held.state) === 'sent' || (held == null ? void 0 : held.state) === 'skipped') return false;
+            if ((held == null ? void 0 : held.state) === 'sending' && now - Number((_held_atMs = held.atMs) != null ? _held_atMs : 0) < EMAIL_CLAIM_STALE_MS) return false;
+            transaction.set(ref, {
+                buyerEmails: {
+                    [key]: {
+                        state: 'sending',
+                        atMs: now
+                    }
+                }
+            }, {
+                merge: true
+            });
+            return true;
+        });
+        if (!claimed) return 'already';
+        const outcome = await sendPosHardwareEmail(kind, orderId, order);
+        await ref.set({
+            buyerEmails: {
+                [key]: {
+                    state: outcome === 'sent' ? 'sent' : outcome,
+                    atMs: Date.now()
+                }
+            }
+        }, {
+            merge: true
+        }).catch((error)=>console.error('[pos-hardware] email claim not settled', kind, orderId, error));
+        return outcome;
+    } catch (error) {
+        console.error('[pos-hardware] email claim failed', kind, orderId, error);
+        return 'failed';
+    }
+}
+/**
+ * The invitation to sign up (AGL-4038), for someone who bought a card reader
+ * in person at the platform's own store with no account yet: create the
+ * account with this address and the order joins their workspace on its own.
+ * Sent in the selling workspace's brand, which is the platform's. Never
+ * throws; the caller has already claimed the send.
+ */ /** The invitation's merge values. Exported for the render spec. */ export function posHardwareInviteMerge(orderId, order) {
+    var _order_totalCents;
+    return {
+        'order.number': posHardwareOrderNumber(orderId),
+        'order.items': itemsText(order),
+        'order.total': formatPosHardwareCents((_order_totalCents = order.totalCents) != null ? _order_totalCents : 0),
+        'order.signUpUrl': `${platformConsoleOrigin()}/signup`
+    };
+}
+export async function sendPosHardwareInvite(orderId, order) {
+    try {
+        var _ref, _ref1;
+        var _order_attachment, _order_posSale;
+        const to = String((_ref = (_order_attachment = order.attachment) == null ? void 0 : _order_attachment.email) != null ? _ref : '').trim();
+        if (!to) return;
+        const [recipient] = await filterSuppressedEmails([
+            to
+        ]);
+        if (!recipient) return;
+        const merge = posHardwareInviteMerge(orderId, order);
+        const signUpUrl = merge['order.signUpUrl'];
+        const subject = FALLBACK.invited(merge['order.number']);
+        const brand = await orgSystemEmailBrand((_ref1 = (_order_posSale = order.posSale) == null ? void 0 : _order_posSale.orgId) != null ? _ref1 : order.orgId);
+        const content = await renderSystemEmailContent(POS_HARDWARE_EMAIL_KEYS.invited, merge, brand, {
+            subject,
+            text: `${subject}\n\n${merge['order.items']}\n\nCreate your account with this email address: ${signUpUrl}`
+        });
+        const result = await sendEmail(_extends({
+            to: recipient
+        }, content, brand.fromName ? {
+            fromName: brand.fromName
+        } : {}, {
+            context: POS_HARDWARE_EMAIL_KEYS.invited
+        }));
+        if (result.sent) await meterPlatformEmail(1);
+    } catch (error) {
+        console.error('[pos-hardware] invitation failed', orderId, error);
+    }
+}
+/**
+ * A closure canceled an order staff had already placed with Stripe: the
+ * merchant is refunded, and Stripe will still ship it unless someone cancels
+ * it there. Once per order.
+ */ export async function raisePosHardwareCanceledAfterOrderingAlert(orderId, order, reason) {
+    try {
+        var _order_stripeHardwareOrderId, _order_totalCents, _order_lines;
+        const stripeOrderId = String((_order_stripeHardwareOrderId = order.stripeHardwareOrderId) != null ? _order_stripeHardwareOrderId : '').trim();
+        await raiseOperatorAlert(COMMERCE_POS_HARDWARE_CANCELED_AFTER_ORDERING, {
+            dedupeKey: orderId,
+            orgId: order.orgId,
+            hostId: order.hostId,
+            context: {
+                orderNumber: posHardwareOrderNumber(orderId),
+                amount: formatOperatorAlertAmount((_order_totalCents = order.totalCents) != null ? _order_totalCents : 0),
+                items: ((_order_lines = order.lines) != null ? _order_lines : []).map((line)=>`${line.quantity} × ${line.name}`).join(', '),
+                reason: staffReasonText(reason, order.orgId),
+                stripeOrder: stripeOrderId ? ` (Stripe order ${stripeOrderId})` : ''
+            }
+        });
+    } catch (error) {
+        console.error('[pos-hardware] canceled-after-ordering alert failed', orderId, error);
+    }
+}
+/**
+ * Stripe refused a closure's refund, and the closure went ahead without it.
+ * Carries the payment to refund by hand, never the buyer.
+ */ export async function raisePosHardwareRefundFailedAlert(orderId, order, reason, error) {
+    try {
+        var _order_stripeHardwareOrderId, _order_totalCents, _order_stripePaymentIntentId;
+        const stripeOrderId = String((_order_stripeHardwareOrderId = order.stripeHardwareOrderId) != null ? _order_stripeHardwareOrderId : '').trim();
+        await raiseOperatorAlert(COMMERCE_POS_HARDWARE_REFUND_FAILED, {
+            dedupeKey: orderId,
+            orgId: order.orgId,
+            hostId: order.hostId,
+            context: {
+                orderNumber: posHardwareOrderNumber(orderId),
+                amount: formatOperatorAlertAmount((_order_totalCents = order.totalCents) != null ? _order_totalCents : 0),
+                reason: staffReasonText(reason, order.orgId),
+                error: error || 'no reason given',
+                paymentIntentId: (_order_stripePaymentIntentId = order.stripePaymentIntentId) != null ? _order_stripePaymentIntentId : 'for this order (no payment id is recorded on it)',
+                orderedNote: order.status === 'ordered' ? `. It had already been placed with Stripe${stripeOrderId ? ` as ${stripeOrderId}` : ''}, so cancel it there too before it ships` : ''
+            }
+        });
+    } catch (failure) {
+        console.error('[pos-hardware] refund-failed alert failed', orderId, failure);
     }
 }
 /** "New hardware order", once per order. */ export async function raisePosHardwareOrderAlert(orderId, order) {