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

package/src/lib/server/pos-hardware-sale-fields.js

@@ -0,0 +1,44 @@
+/**
+ * @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 { isPosHardwareSkuId, parsePosHardwareInPersonConfig } from "../model/pos-hardware.js";
+/*==========================================
+ * THE MARK A REGISTER SALE OF HARDWARE CARRIES (AGL-4038).
+ *
+ * Every path that writes a register sale — an open sale, a payment link, a
+ * cash or room sale, the kiosk's cart, an offline sale synced later — spreads
+ * these fields into the order it writes. On the platform's own store, a sale
+ * with a line whose product is a hardware item says `hardwareSalePending`
+ * from the moment it exists, and the hardware order is recorded when it is
+ * paid. The completion listener clears the mark; one it missed is found by
+ * the mark and recorded on the next sweep, so a sale is never lost because a
+ * listener failed after the money was taken.
+ *
+ * Read on every sale of every store, so it costs nothing anywhere but the
+ * seller: the environment is read first, and the products are the ones the
+ * sale already loaded.
+ *=========================================*/ export function posHardwareSaleFields(input, env = process.env) {
+    const config = parsePosHardwareInPersonConfig(env);
+    if (!config || config.sellerHostId !== input.hostId || config.sellerOrgId !== input.orgId) return {};
+    const sellsHardware = input.lineItems.some((line)=>{
+        var _input_products_get;
+        return isPosHardwareSkuId((_input_products_get = input.products.get(line.productId)) == null ? void 0 : _input_products_get.hardwareSku);
+    });
+    return sellsHardware ? {
+        hardwareSalePending: true
+    } : {};
+}
+
+//# sourceMappingURL=pos-hardware-sale-fields.js.map

package/src/lib/server/pos-hardware-sale-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/pos-hardware-sale-fields.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 { isPosHardwareSkuId, parsePosHardwareInPersonConfig } from '../model/pos-hardware'\n\n/*==========================================\n * THE MARK A REGISTER SALE OF HARDWARE CARRIES (AGL-4038).\n *\n * Every path that writes a register sale — an open sale, a payment link, a\n * cash or room sale, the kiosk's cart, an offline sale synced later — spreads\n * these fields into the order it writes. On the platform's own store, a sale\n * with a line whose product is a hardware item says `hardwareSalePending`\n * from the moment it exists, and the hardware order is recorded when it is\n * paid. The completion listener clears the mark; one it missed is found by\n * the mark and recorded on the next sweep, so a sale is never lost because a\n * listener failed after the money was taken.\n *\n * Read on every sale of every store, so it costs nothing anywhere but the\n * seller: the environment is read first, and the products are the ones the\n * sale already loaded.\n *=========================================*/\n\nexport function posHardwareSaleFields(\n  input: {\n    hostId: string\n    orgId: string | null | undefined\n    lineItems: ReadonlyArray<{ productId: string }>\n    products: ReadonlyMap<string, { hardwareSku?: unknown } | null | undefined>\n  },\n  env: Record<string, string | undefined> = process.env,\n): { hardwareSalePending?: true } {\n  const config = parsePosHardwareInPersonConfig(env)\n  if (!config || config.sellerHostId !== input.hostId || config.sellerOrgId !== input.orgId) return {}\n  const sellsHardware = input.lineItems.some((line) =>\n    isPosHardwareSkuId(input.products.get(line.productId)?.hardwareSku),\n  )\n  return sellsHardware ? { hardwareSalePending: true } : {}\n}\n"],"names":["isPosHardwareSkuId","parsePosHardwareInPersonConfig","posHardwareSaleFields","input","env","process","config","sellerHostId","hostId","sellerOrgId","orgId","sellsHardware","lineItems","some","line","products","get","productId","hardwareSku","hardwareSalePending"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,kBAAkB,EAAEC,8BAA8B,QAAQ,2BAAuB;AAE1F;;;;;;;;;;;;;;;2CAe2C,GAE3C,OAAO,SAASC,sBACdC,KAKC,EACDC,MAA0CC,QAAQD,GAAG;IAErD,MAAME,SAASL,+BAA+BG;IAC9C,IAAI,CAACE,UAAUA,OAAOC,YAAY,KAAKJ,MAAMK,MAAM,IAAIF,OAAOG,WAAW,KAAKN,MAAMO,KAAK,EAAE,OAAO,CAAC;IACnG,MAAMC,gBAAgBR,MAAMS,SAAS,CAACC,IAAI,CAAC,CAACC;YACvBX;eAAnBH,oBAAmBG,sBAAAA,MAAMY,QAAQ,CAACC,GAAG,CAACF,KAAKG,SAAS,sBAAjCd,oBAAoCe,WAAW;;IAEpE,OAAOP,gBAAgB;QAAEQ,qBAAqB;IAAK,IAAI,CAAC;AAC1D"}

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

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { PluginApiHandler } from '@aglyn/aglyn/server';
+import { type PosHardwareOrder } from '../model/pos-hardware';
+/** How many lookups one register user makes in ten minutes. */
+export declare const BUYER_LOOKUPS_PER_WINDOW = 30;
+export declare const posHardwareSaleHandler: PluginApiHandler;
+/**
+ * A sale on the To attach list, as the register shows it: what was sold and
+ * when, the register order it came from, and what is known of the buyer —
+ * the receipt address, or the address or account a register user gave.
+ */
+export declare function toAttachView(id: string, order: PosHardwareOrder): {
+    id: string;
+    number: string;
+    registerOrderId: string;
+    registerNumber: number;
+    kiosk: boolean;
+    offline: boolean;
+    lines: {
+        sku: import("../model/pos-hardware").PosHardwareSkuId;
+        name: string;
+        quantity: number;
+    }[];
+    totalCents: number;
+    createdAtMs: number;
+    contactEmail: string;
+    attached: boolean;
+    /** Attached with the buyer's store chosen: a reader can be registered to it here. */
+    storeChosen: boolean;
+    /** Readers on the sale, and how many have a serial or are set up. */
+    readers: number;
+    serialsTaken: number;
+    readersSetUp: number;
+    /** A buyer with an account and no workspace yet. */
+    awaitingWorkspace: boolean;
+    /** A buyer with no account yet, invited to sign up. */
+    invited: boolean;
+};
+export type ToAttachView = ReturnType<typeof toAttachView>;

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

@@ -0,0 +1,369 @@
+/**
+ * @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 { _ as _extends } from "@swc/helpers/_/_extends";
+import { consumeRateLimit, firebaseAdmin } from "@aglyn/tenant-data-admin";
+import { addAdminAudit } from "@aglyn/tenant-data-admin/server/admin-audit-write";
+import { maskEmailAddress } from "@aglyn/tenant-data-admin/server/admin-audit";
+import { POS_HARDWARE_SKUS } from "../model/pos-hardware.js";
+import { authorizePosStaff, posIdempotencyKey, posRequestBody } from "./pos-auth.js";
+import { isPosHardwareSellerStore, posHardwareInPersonConfig, posHardwareOrderNumber } from "./pos-hardware.js";
+/** How many lookups one register user makes in ten minutes. */ export const BUYER_LOOKUPS_PER_WINDOW = 30;
+const LOOKUP_WINDOW_MS = 10 * 60 * 1000;
+/*==========================================
+ * `POST /api/commerce/pos-hardware-sale` (AGL-4038): selling a card reader in
+ * person, at the platform's own store's register, to someone who is not a
+ * member of it.
+ *
+ *   status   whether this store is the platform's hardware seller, and the
+ *            hardware items a product of it may be — the product editor's
+ *            "Point of sale hardware" choice is shown only where it is.
+ *   pending  the "To attach" list: sales of hardware nobody has said whose
+ *            they are yet (a kiosk or offline sale, a buyer with no account
+ *            or no workspace yet), newest first. Records any paid sale still
+ *            waiting to be recorded first (`sweepInPersonPosHardwareSales`).
+ *   find     look the buyer up across the platform by exact email, a
+ *            person's name or a workspace's name (`pos-hardware-buyer-lookup.ts`):
+ *            the least that picks the right person, their address in full.
+ *            Rate-limited per register user and written to the platform's
+ *            audit log (the address masked there), every time.
+ *   attach   say whose a sale is — by the register sale or the To attach
+ *            entry — as an account and workspace (and store), an account
+ *            with no workspace yet, or the address of someone with no
+ *            account, who is invited to sign up (`pos-hardware-attach.ts`).
+ *            Idempotency-Key required; audited.
+ *   detach   put an attached sale back on the To attach list. Audited.
+ *   serials  the serial numbers of the sale's readers, scanned or typed at
+ *            the sale, so the order sets itself up when the buyer registers
+ *            them (`pos-hardware-readers.ts`).
+ *   terms    the terms of sale the buyer accepts before paying (Terms
+ *            4.26–4.32 in short, with the link), and `terms-status` whether
+ *            they have, for the register waiting on its display.
+ *   accept-terms  the buyer accepted on the register tablet handed to them;
+ *            `terms-on-display` notes who is putting them on the customer
+ *            display, before the register shows them there (`pos-hardware-terms.ts`).
+ *   register-at-booth  register a reader to the buyer's chosen store by the
+ *            code it shows, while they are there, with the store's address
+ *            when it has no reader Location yet (`address`; refused with
+ *            `reason: 'needs-address'` without one). Idempotency-Key
+ *            required; audited.
+ *
+ * `status` is asked of whoever works the register; everything else needs
+ * "Sell at the register" (`posSell`) on the seller store, since it is part
+ * of ringing a sale there, and answers 404 on any other store.
+ *
+ * Gated like the register (`authorizePosStaff`, on a plan with POS). Every
+ * answer is about THIS store: on any store but the configured seller it says
+ * `seller: false` and nothing else, so no other workspace learns the
+ * platform's configuration or is shown a control it cannot use.
+ *=========================================*/ export const posHardwareSaleHandler = async (req, res)=>{
+    var _body_hostId, _body_action;
+    if (req.method !== 'POST') return res.status(405).json({
+        error: 'Method not allowed'
+    });
+    const body = posRequestBody(req);
+    const hostId = String((_body_hostId = body['hostId']) != null ? _body_hostId : '');
+    const action = String((_body_action = body['action']) != null ? _body_action : '');
+    const permission = action === 'status' ? undefined : 'posSell';
+    const gate = await authorizePosStaff(req, hostId, permission);
+    if ('error' in gate) return res.status(gate.status).json({
+        error: gate.error
+    });
+    const staff = gate.staff;
+    const config = posHardwareInPersonConfig();
+    const seller = isPosHardwareSellerStore(config, staff.hostId, staff.orgId);
+    try {
+        if (action === 'status') {
+            if (!seller) return res.status(200).json({
+                seller: false
+            });
+            return res.status(200).json({
+                seller: true,
+                items: POS_HARDWARE_SKUS.map((sku)=>({
+                        sku: sku.id,
+                        name: sku.displayName,
+                        kind: sku.kind
+                    }))
+            });
+        }
+        if (!seller) return res.status(404).json({
+            error: 'Card reader sales are not available on this store.'
+        });
+        const inPerson = await import("./pos-hardware-in-person.js");
+        switch(action){
+            case 'pending':
+                {
+                    await inPerson.sweepInPersonPosHardwareSales(config);
+                    const pending = await inPerson.pendingInPersonPosHardwareOrders(config);
+                    return res.status(200).json({
+                        orders: pending.map(({ id, order })=>toAttachView(id, order))
+                    });
+                }
+            case 'find':
+                {
+                    var _body_query;
+                    const query = String((_body_query = body['query']) != null ? _body_query : '').trim().slice(0, 120);
+                    if (query.length < 2) return res.status(400).json({
+                        error: 'Type at least two letters, or an email address.'
+                    });
+                    const rate = await consumeRateLimit(`pos-hardware-lookup:${staff.uid}`, {
+                        limit: BUYER_LOOKUPS_PER_WINDOW,
+                        windowMs: LOOKUP_WINDOW_MS
+                    });
+                    if (!rate.allowed) return res.status(429).json({
+                        error: 'Too many lookups. Try again in a few minutes.'
+                    });
+                    const found = await (await import("./pos-hardware-buyer-lookup.js")).findHardwareBuyers(query);
+                    await audit(staff, 'pos-hardware-buyer-lookup', {
+                        // The audit log keeps an address masked; a name as typed. The
+                        // register itself is answered in full.
+                        query: found.kind === 'email' ? maskEmailAddress(query) : query,
+                        kind: found.kind,
+                        matched: [
+                            ...found.people.map((person)=>person.uid),
+                            ...found.workspaces.map((workspace)=>`org:${workspace.orgId}`)
+                        ]
+                    });
+                    return res.status(200).json(found);
+                }
+            case 'terms':
+            case 'terms-status':
+            case 'terms-on-display':
+            case 'accept-terms':
+                {
+                    var _body_registerOrderId;
+                    const terms = await import("./pos-hardware-terms.js");
+                    const registerOrderId = String((_body_registerOrderId = body['registerOrderId']) != null ? _body_registerOrderId : '');
+                    try {
+                        if (action === 'terms') return res.status(200).json(terms.posHardwareTermsView());
+                        if (action === 'terms-status') {
+                            return res.status(200).json(await terms.posHardwareTermsStatus(config, registerOrderId));
+                        }
+                        if (action === 'terms-on-display') {
+                            await terms.requestPosHardwareTermsOnDisplay({
+                                config,
+                                registerOrderId,
+                                uid: staff.uid
+                            });
+                            return res.status(200).json({
+                                ok: true
+                            });
+                        }
+                        const device = terms.posHardwareTermsDevice(req.headers);
+                        const acceptance = await terms.recordPosHardwareTermsAcceptance(_extends({
+                            config,
+                            registerOrderId,
+                            method: 'tablet',
+                            staffUid: staff.uid
+                        }, device));
+                        await audit(staff, 'pos-hardware-terms-accepted', {
+                            method: acceptance.method,
+                            version: acceptance.version,
+                            registerOrderId
+                        }, null);
+                        return res.status(200).json({
+                            ok: true,
+                            acceptance
+                        });
+                    } catch (error) {
+                        if (error instanceof terms.PosHardwareTermsRefusal) {
+                            return res.status(error.status).json({
+                                error: error.message
+                            });
+                        }
+                        throw error;
+                    }
+                }
+            case 'serials':
+            case 'register-at-booth':
+                {
+                    const readers = await import("./pos-hardware-readers.js");
+                    try {
+                        var _body_orderId, _storeAddress_state;
+                        if (action === 'serials') {
+                            const saved = await readers.recordPosHardwareSerials({
+                                config,
+                                registerOrderId: typeof body['registerOrderId'] === 'string' ? body['registerOrderId'] : null,
+                                orderId: typeof body['orderId'] === 'string' ? body['orderId'] : null,
+                                serials: body['serials']
+                            });
+                            return res.status(200).json({
+                                ok: true,
+                                serials: saved.serials,
+                                recorded: saved.recorded
+                            });
+                        }
+                        if (!posIdempotencyKey(req)) return res.status(400).json({
+                            error: 'Missing Idempotency-Key'
+                        });
+                        const registerOrderId = typeof body['registerOrderId'] === 'string' ? body['registerOrderId'] : '';
+                        const orderId = registerOrderId ? (await import("./pos-hardware.js")).posHardwareInPersonOrderId(config.sellerHostId, registerOrderId) : String((_body_orderId = body['orderId']) != null ? _body_orderId : '');
+                        const { order, readerId, storeAddress } = await readers.registerPosHardwareAtBooth({
+                            config,
+                            orderId,
+                            registrationCode: body['registrationCode'],
+                            label: body['label'],
+                            address: body['address'],
+                            uid: staff.uid
+                        });
+                        await audit(staff, 'pos-hardware-register-at-booth', _extends({
+                            readerId,
+                            hostId: order.hostId,
+                            orgId: order.orgId
+                        }, storeAddress ? {
+                            storeAddressEntered: {
+                                city: storeAddress.city,
+                                state: (_storeAddress_state = storeAddress.state) != null ? _storeAddress_state : null,
+                                country: storeAddress.country
+                            }
+                        } : {}), orderId);
+                        return res.status(200).json({
+                            ok: true,
+                            readerId,
+                            storeAddressSaved: Boolean(storeAddress),
+                            order: toAttachView(orderId, order)
+                        });
+                    } catch (error) {
+                        if (error instanceof readers.PosHardwareReaderRefusal) {
+                            return res.status(error.status).json(_extends({
+                                error: error.message
+                            }, error.reason ? {
+                                reason: error.reason
+                            } : {}));
+                        }
+                        throw error;
+                    }
+                }
+            case 'attach':
+            case 'detach':
+                {
+                    if (!posIdempotencyKey(req)) return res.status(400).json({
+                        error: 'Missing Idempotency-Key'
+                    });
+                    const attach = await import("./pos-hardware-attach.js");
+                    try {
+                        var _body_buyer;
+                        if (action === 'detach') {
+                            var _body_orderId1;
+                            const orderId = String((_body_orderId1 = body['orderId']) != null ? _body_orderId1 : '');
+                            const { order } = await attach.detachPosHardwareSale({
+                                config,
+                                orderId
+                            });
+                            await audit(staff, 'pos-hardware-sale-detach', {
+                                orderId
+                            }, orderId);
+                            return res.status(200).json({
+                                ok: true,
+                                order: toAttachView(orderId, order)
+                            });
+                        }
+                        const buyer = await attach.checkHardwareBuyer((_body_buyer = body['buyer']) != null ? _body_buyer : {});
+                        const outcome = await attach.attachPosHardwareSale({
+                            config,
+                            buyer,
+                            attachedBy: staff.uid,
+                            registerOrderId: typeof body['registerOrderId'] === 'string' ? body['registerOrderId'] : null,
+                            orderId: typeof body['orderId'] === 'string' ? body['orderId'] : null
+                        });
+                        const target = outcome.outcome === 'waiting' ? null : outcome.orderId;
+                        await audit(staff, 'pos-hardware-sale-attach', _extends({
+                            outcome: outcome.outcome,
+                            uid: buyer.uid,
+                            orgId: buyer.orgId,
+                            hostId: buyer.hostId,
+                            email: buyer.uid ? null : maskEmailAddress(buyer.email)
+                        }, outcome.outcome === 'waiting' ? {
+                            registerOrderId: outcome.registerOrderId
+                        } : {}), target);
+                        return res.status(200).json(outcome.outcome === 'waiting' ? {
+                            outcome: 'waiting'
+                        } : {
+                            outcome: outcome.outcome,
+                            order: toAttachView(outcome.orderId, outcome.order)
+                        });
+                    } catch (error) {
+                        if (error instanceof attach.PosHardwareAttachRefusal) {
+                            return res.status(error.status).json({
+                                error: error.message
+                            });
+                        }
+                        throw error;
+                    }
+                }
+            default:
+                return res.status(400).json({
+                    error: 'Unknown action'
+                });
+        }
+    } catch (error) {
+        console.error('[pos-hardware-sale]', action, error);
+        return res.status(500).json({
+            error: 'The card reader sale could not answer'
+        });
+    }
+};
+/**
+ * A sale on the To attach list, as the register shows it: what was sold and
+ * when, the register order it came from, and what is known of the buyer —
+ * the receipt address, or the address or account a register user gave.
+ */ export function toAttachView(id, order) {
+    var _ref, _ref1, _order_lines, _order_totalCents, _order_createdAtMs, _order_contactEmail, _order_units, _order_units1, _order_units2;
+    var _order_posSale, _order_posSale1, _order_posSale2, _order_posSale3, _order_attachment, _order_attachment1, _order_attachment2, _order_attachment3, _order_attachment4;
+    return {
+        id,
+        number: posHardwareOrderNumber(id),
+        registerOrderId: (_ref = (_order_posSale = order.posSale) == null ? void 0 : _order_posSale.orderId) != null ? _ref : null,
+        registerNumber: (_ref1 = (_order_posSale1 = order.posSale) == null ? void 0 : _order_posSale1.number) != null ? _ref1 : null,
+        kiosk: ((_order_posSale2 = order.posSale) == null ? void 0 : _order_posSale2.kiosk) === true,
+        offline: ((_order_posSale3 = order.posSale) == null ? void 0 : _order_posSale3.offline) === true,
+        lines: ((_order_lines = order.lines) != null ? _order_lines : []).map((line)=>({
+                sku: line.sku,
+                name: line.name,
+                quantity: line.quantity
+            })),
+        totalCents: (_order_totalCents = order.totalCents) != null ? _order_totalCents : 0,
+        createdAtMs: (_order_createdAtMs = order.createdAtMs) != null ? _order_createdAtMs : 0,
+        // The buyer's address in full, as the lookup shows it (AGL-4038): the
+        // account's, a receipt's, or one typed for a buyer with no account.
+        contactEmail: (_order_contactEmail = order.contactEmail) != null ? _order_contactEmail : null,
+        attached: ((_order_attachment = order.attachment) == null ? void 0 : _order_attachment.state) === 'attached',
+        /** Attached with the buyer's store chosen: a reader can be registered to it here. */ storeChosen: ((_order_attachment1 = order.attachment) == null ? void 0 : _order_attachment1.state) === 'attached' && Boolean(order.hostId),
+        /** Readers on the sale, and how many have a serial or are set up. */ readers: ((_order_units = order.units) != null ? _order_units : []).length,
+        serialsTaken: ((_order_units1 = order.units) != null ? _order_units1 : []).filter((unit)=>unit.serialNumber).length,
+        readersSetUp: ((_order_units2 = order.units) != null ? _order_units2 : []).filter((unit)=>unit.readerId).length,
+        /** A buyer with an account and no workspace yet. */ awaitingWorkspace: Boolean((_order_attachment2 = order.attachment) == null ? void 0 : _order_attachment2.uid),
+        /** A buyer with no account yet, invited to sign up. */ invited: Boolean(((_order_attachment3 = order.attachment) == null ? void 0 : _order_attachment3.email) && !((_order_attachment4 = order.attachment) == null ? void 0 : _order_attachment4.uid))
+    };
+}
+/**
+ * One row of the platform's audit log for a lookup or an attachment: who on
+ * the selling store did it, and what — never the buyer's full address.
+ */ async function audit(staff, action, after, orderId = null) {
+    const firestore = firebaseAdmin.app().firestore();
+    await addAdminAudit(firestore, {
+        action,
+        actorUid: staff.uid,
+        actorEmail: null,
+        scope: 'posHardwareSale',
+        target: orderId ? `posHardwareSales/${orderId}` : `hosts/${staff.hostId}`,
+        orgId: staff.orgId,
+        before: null,
+        after,
+        at: firebaseAdmin.firestore.FieldValue.serverTimestamp()
+    });
+}
+
+//# sourceMappingURL=pos-hardware-sale.js.map

package/src/lib/server/pos-hardware-sale.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/pos-hardware-sale.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 { PluginApiHandler } from '@aglyn/aglyn/server'\nimport { consumeRateLimit, firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport { addAdminAudit } from '@aglyn/tenant-data-admin/server/admin-audit-write'\nimport { maskEmailAddress } from '@aglyn/tenant-data-admin/server/admin-audit'\nimport { POS_HARDWARE_SKUS, type PosHardwareOrder } from '../model/pos-hardware'\nimport type { PosPermission } from '../model/plugin-permissions'\nimport { authorizePosStaff, posIdempotencyKey, posRequestBody, type PosStaff } from './pos-auth'\nimport { isPosHardwareSellerStore, posHardwareInPersonConfig, posHardwareOrderNumber } from './pos-hardware'\n\n/** How many lookups one register user makes in ten minutes. */\nexport const BUYER_LOOKUPS_PER_WINDOW = 30\nconst LOOKUP_WINDOW_MS = 10 * 60 * 1000\n\n/*==========================================\n * `POST /api/commerce/pos-hardware-sale` (AGL-4038): selling a card reader in\n * person, at the platform's own store's register, to someone who is not a\n * member of it.\n *\n *   status   whether this store is the platform's hardware seller, and the\n *            hardware items a product of it may be — the product editor's\n *            \"Point of sale hardware\" choice is shown only where it is.\n *   pending  the \"To attach\" list: sales of hardware nobody has said whose\n *            they are yet (a kiosk or offline sale, a buyer with no account\n *            or no workspace yet), newest first. Records any paid sale still\n *            waiting to be recorded first (`sweepInPersonPosHardwareSales`).\n *   find     look the buyer up across the platform by exact email, a\n *            person's name or a workspace's name (`pos-hardware-buyer-lookup.ts`):\n *            the least that picks the right person, their address in full.\n *            Rate-limited per register user and written to the platform's\n *            audit log (the address masked there), every time.\n *   attach   say whose a sale is — by the register sale or the To attach\n *            entry — as an account and workspace (and store), an account\n *            with no workspace yet, or the address of someone with no\n *            account, who is invited to sign up (`pos-hardware-attach.ts`).\n *            Idempotency-Key required; audited.\n *   detach   put an attached sale back on the To attach list. Audited.\n *   serials  the serial numbers of the sale's readers, scanned or typed at\n *            the sale, so the order sets itself up when the buyer registers\n *            them (`pos-hardware-readers.ts`).\n *   terms    the terms of sale the buyer accepts before paying (Terms\n *            4.26–4.32 in short, with the link), and `terms-status` whether\n *            they have, for the register waiting on its display.\n *   accept-terms  the buyer accepted on the register tablet handed to them;\n *            `terms-on-display` notes who is putting them on the customer\n *            display, before the register shows them there (`pos-hardware-terms.ts`).\n *   register-at-booth  register a reader to the buyer's chosen store by the\n *            code it shows, while they are there, with the store's address\n *            when it has no reader Location yet (`address`; refused with\n *            `reason: 'needs-address'` without one). Idempotency-Key\n *            required; audited.\n *\n * `status` is asked of whoever works the register; everything else needs\n * \"Sell at the register\" (`posSell`) on the seller store, since it is part\n * of ringing a sale there, and answers 404 on any other store.\n *\n * Gated like the register (`authorizePosStaff`, on a plan with POS). Every\n * answer is about THIS store: on any store but the configured seller it says\n * `seller: false` and nothing else, so no other workspace learns the\n * platform's configuration or is shown a control it cannot use.\n *=========================================*/\n\nexport const posHardwareSaleHandler: PluginApiHandler = async (req, res) => {\n  if (req.method !== 'POST') return res.status(405).json({ error: 'Method not allowed' })\n  const body = posRequestBody(req)\n  const hostId = String(body['hostId'] ?? '')\n  const action = String(body['action'] ?? '')\n  const permission: PosPermission | undefined = action === 'status' ? undefined : 'posSell'\n  const gate = await authorizePosStaff(req, hostId, permission)\n  if ('error' in gate) return res.status(gate.status).json({ error: gate.error })\n  const staff = gate.staff\n  const config = posHardwareInPersonConfig()\n  const seller = isPosHardwareSellerStore(config, staff.hostId, staff.orgId)\n  try {\n    if (action === 'status') {\n      if (!seller) return res.status(200).json({ seller: false })\n      return res.status(200).json({\n        seller: true,\n        items: POS_HARDWARE_SKUS.map((sku) => ({ sku: sku.id, name: sku.displayName, kind: sku.kind })),\n      })\n    }\n    if (!seller) return res.status(404).json({ error: 'Card reader sales are not available on this store.' })\n    const inPerson = await import('./pos-hardware-in-person')\n    switch (action) {\n      case 'pending': {\n        await inPerson.sweepInPersonPosHardwareSales(config)\n        const pending = await inPerson.pendingInPersonPosHardwareOrders(config)\n        return res.status(200).json({ orders: pending.map(({ id, order }) => toAttachView(id, order)) })\n      }\n      case 'find': {\n        const query = String(body['query'] ?? '').trim().slice(0, 120)\n        if (query.length < 2) return res.status(400).json({ error: 'Type at least two letters, or an email address.' })\n        const rate = await consumeRateLimit(`pos-hardware-lookup:${staff.uid}`, {\n          limit: BUYER_LOOKUPS_PER_WINDOW,\n          windowMs: LOOKUP_WINDOW_MS,\n        })\n        if (!rate.allowed) return res.status(429).json({ error: 'Too many lookups. Try again in a few minutes.' })\n        const found = await (await import('./pos-hardware-buyer-lookup')).findHardwareBuyers(query)\n        await audit(staff, 'pos-hardware-buyer-lookup', {\n          // The audit log keeps an address masked; a name as typed. The\n          // register itself is answered in full.\n          query: found.kind === 'email' ? maskEmailAddress(query) : query,\n          kind: found.kind,\n          matched: [\n            ...found.people.map((person) => person.uid),\n            ...found.workspaces.map((workspace) => `org:${workspace.orgId}`),\n          ],\n        })\n        return res.status(200).json(found)\n      }\n      case 'terms':\n      case 'terms-status':\n      case 'terms-on-display':\n      case 'accept-terms': {\n        const terms = await import('./pos-hardware-terms')\n        const registerOrderId = String(body['registerOrderId'] ?? '')\n        try {\n          if (action === 'terms') return res.status(200).json(terms.posHardwareTermsView())\n          if (action === 'terms-status') {\n            return res.status(200).json(await terms.posHardwareTermsStatus(config, registerOrderId))\n          }\n          if (action === 'terms-on-display') {\n            await terms.requestPosHardwareTermsOnDisplay({ config, registerOrderId, uid: staff.uid })\n            return res.status(200).json({ ok: true })\n          }\n          const device = terms.posHardwareTermsDevice(req.headers as Record<string, unknown>)\n          const acceptance = await terms.recordPosHardwareTermsAcceptance({\n            config,\n            registerOrderId,\n            method: 'tablet',\n            staffUid: staff.uid,\n            ...device,\n          })\n          await audit(staff, 'pos-hardware-terms-accepted', { method: acceptance.method, version: acceptance.version, registerOrderId }, null)\n          return res.status(200).json({ ok: true, acceptance })\n        } catch (error) {\n          if (error instanceof terms.PosHardwareTermsRefusal) {\n            return res.status(error.status).json({ error: error.message })\n          }\n          throw error\n        }\n      }\n      case 'serials':\n      case 'register-at-booth': {\n        const readers = await import('./pos-hardware-readers')\n        try {\n          if (action === 'serials') {\n            const saved = await readers.recordPosHardwareSerials({\n              config,\n              registerOrderId: typeof body['registerOrderId'] === 'string' ? body['registerOrderId'] : null,\n              orderId: typeof body['orderId'] === 'string' ? body['orderId'] : null,\n              serials: body['serials'],\n            })\n            return res.status(200).json({ ok: true, serials: saved.serials, recorded: saved.recorded })\n          }\n          if (!posIdempotencyKey(req)) return res.status(400).json({ error: 'Missing Idempotency-Key' })\n          const registerOrderId = typeof body['registerOrderId'] === 'string' ? body['registerOrderId'] : ''\n          const orderId = registerOrderId\n            ? (await import('./pos-hardware')).posHardwareInPersonOrderId(config.sellerHostId, registerOrderId)\n            : String(body['orderId'] ?? '')\n          const { order, readerId, storeAddress } = await readers.registerPosHardwareAtBooth({\n            config,\n            orderId,\n            registrationCode: body['registrationCode'],\n            label: body['label'],\n            address: body['address'],\n            uid: staff.uid,\n          })\n          await audit(\n            staff,\n            'pos-hardware-register-at-booth',\n            {\n              readerId,\n              hostId: order.hostId,\n              orgId: order.orgId,\n              // That the buyer's store address was typed here, and where:\n              // the store's reader Location was made from it. The street\n              // stays with the store, never in the audit log.\n              ...(storeAddress\n                ? {\n                    storeAddressEntered: {\n                      city: storeAddress.city,\n                      state: storeAddress.state ?? null,\n                      country: storeAddress.country,\n                    },\n                  }\n                : {}),\n            },\n            orderId,\n          )\n          return res.status(200).json({\n            ok: true,\n            readerId,\n            storeAddressSaved: Boolean(storeAddress),\n            order: toAttachView(orderId, order),\n          })\n        } catch (error) {\n          if (error instanceof readers.PosHardwareReaderRefusal) {\n            return res\n              .status(error.status)\n              .json({ error: error.message, ...(error.reason ? { reason: error.reason } : {}) })\n          }\n          throw error\n        }\n      }\n      case 'attach':\n      case 'detach': {\n        if (!posIdempotencyKey(req)) return res.status(400).json({ error: 'Missing Idempotency-Key' })\n        const attach = await import('./pos-hardware-attach')\n        try {\n          if (action === 'detach') {\n            const orderId = String(body['orderId'] ?? '')\n            const { order } = await attach.detachPosHardwareSale({ config, orderId })\n            await audit(staff, 'pos-hardware-sale-detach', { orderId }, orderId)\n            return res.status(200).json({ ok: true, order: toAttachView(orderId, order) })\n          }\n          const buyer = await attach.checkHardwareBuyer((body['buyer'] ?? {}) as Record<string, unknown>)\n          const outcome = await attach.attachPosHardwareSale({\n            config,\n            buyer,\n            attachedBy: staff.uid,\n            registerOrderId: typeof body['registerOrderId'] === 'string' ? body['registerOrderId'] : null,\n            orderId: typeof body['orderId'] === 'string' ? body['orderId'] : null,\n          })\n          const target = outcome.outcome === 'waiting' ? null : outcome.orderId\n          await audit(\n            staff,\n            'pos-hardware-sale-attach',\n            {\n              outcome: outcome.outcome,\n              uid: buyer.uid,\n              orgId: buyer.orgId,\n              hostId: buyer.hostId,\n              email: buyer.uid ? null : maskEmailAddress(buyer.email),\n              ...(outcome.outcome === 'waiting' ? { registerOrderId: outcome.registerOrderId } : {}),\n            },\n            target,\n          )\n          return res.status(200).json(\n            outcome.outcome === 'waiting'\n              ? { outcome: 'waiting' }\n              : { outcome: outcome.outcome, order: toAttachView(outcome.orderId, outcome.order) },\n          )\n        } catch (error) {\n          if (error instanceof attach.PosHardwareAttachRefusal) {\n            return res.status(error.status).json({ error: error.message })\n          }\n          throw error\n        }\n      }\n      default:\n        return res.status(400).json({ error: 'Unknown action' })\n    }\n  } catch (error) {\n    console.error('[pos-hardware-sale]', action, error)\n    return res.status(500).json({ error: 'The card reader sale could not answer' })\n  }\n}\n\n/**\n * A sale on the To attach list, as the register shows it: what was sold and\n * when, the register order it came from, and what is known of the buyer —\n * the receipt address, or the address or account a register user gave.\n */\nexport function toAttachView(id: string, order: PosHardwareOrder) {\n  return {\n    id,\n    number: posHardwareOrderNumber(id),\n    registerOrderId: order.posSale?.orderId ?? null,\n    registerNumber: order.posSale?.number ?? null,\n    kiosk: order.posSale?.kiosk === true,\n    offline: order.posSale?.offline === true,\n    lines: (order.lines ?? []).map((line) => ({ sku: line.sku, name: line.name, quantity: line.quantity })),\n    totalCents: order.totalCents ?? 0,\n    createdAtMs: order.createdAtMs ?? 0,\n    // The buyer's address in full, as the lookup shows it (AGL-4038): the\n    // account's, a receipt's, or one typed for a buyer with no account.\n    contactEmail: order.contactEmail ?? null,\n    attached: order.attachment?.state === 'attached',\n    /** Attached with the buyer's store chosen: a reader can be registered to it here. */\n    storeChosen: order.attachment?.state === 'attached' && Boolean(order.hostId),\n    /** Readers on the sale, and how many have a serial or are set up. */\n    readers: (order.units ?? []).length,\n    serialsTaken: (order.units ?? []).filter((unit) => unit.serialNumber).length,\n    readersSetUp: (order.units ?? []).filter((unit) => unit.readerId).length,\n    /** A buyer with an account and no workspace yet. */\n    awaitingWorkspace: Boolean(order.attachment?.uid),\n    /** A buyer with no account yet, invited to sign up. */\n    invited: Boolean(order.attachment?.email && !order.attachment?.uid),\n  }\n}\n\nexport type ToAttachView = ReturnType<typeof toAttachView>\n\n/**\n * One row of the platform's audit log for a lookup or an attachment: who on\n * the selling store did it, and what — never the buyer's full address.\n */\nasync function audit(\n  staff: PosStaff,\n  action: string,\n  after: Record<string, unknown>,\n  orderId: string | null = null,\n): Promise<void> {\n  const firestore = firebaseAdmin.app().firestore()\n  await addAdminAudit(firestore, {\n    action,\n    actorUid: staff.uid,\n    actorEmail: null,\n    scope: 'posHardwareSale',\n    target: orderId ? `posHardwareSales/${orderId}` : `hosts/${staff.hostId}`,\n    orgId: staff.orgId,\n    before: null,\n    after,\n    at: firebaseAdmin.firestore.FieldValue.serverTimestamp(),\n  })\n}\n"],"names":["consumeRateLimit","firebaseAdmin","addAdminAudit","maskEmailAddress","POS_HARDWARE_SKUS","authorizePosStaff","posIdempotencyKey","posRequestBody","isPosHardwareSellerStore","posHardwareInPersonConfig","posHardwareOrderNumber","BUYER_LOOKUPS_PER_WINDOW","LOOKUP_WINDOW_MS","posHardwareSaleHandler","req","res","body","method","status","json","error","hostId","String","action","permission","undefined","gate","staff","config","seller","orgId","items","map","sku","id","name","displayName","kind","inPerson","sweepInPersonPosHardwareSales","pending","pendingInPersonPosHardwareOrders","orders","order","toAttachView","query","trim","slice","length","rate","uid","limit","windowMs","allowed","found","findHardwareBuyers","audit","matched","people","person","workspaces","workspace","terms","registerOrderId","posHardwareTermsView","posHardwareTermsStatus","requestPosHardwareTermsOnDisplay","ok","device","posHardwareTermsDevice","headers","acceptance","recordPosHardwareTermsAcceptance","staffUid","version","PosHardwareTermsRefusal","message","readers","storeAddress","saved","recordPosHardwareSerials","orderId","serials","recorded","posHardwareInPersonOrderId","sellerHostId","readerId","registerPosHardwareAtBooth","registrationCode","label","address","storeAddressEntered","city","state","country","storeAddressSaved","Boolean","PosHardwareReaderRefusal","reason","attach","detachPosHardwareSale","buyer","checkHardwareBuyer","outcome","attachPosHardwareSale","attachedBy","target","email","PosHardwareAttachRefusal","console","number","posSale","registerNumber","kiosk","offline","lines","line","quantity","totalCents","createdAtMs","contactEmail","attached","attachment","storeChosen","units","serialsTaken","filter","unit","serialNumber","readersSetUp","awaitingWorkspace","invited","after","firestore","app","actorUid","actorEmail","scope","before","at","FieldValue","serverTimestamp"],"mappings":"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"}

package/src/lib/server/pos-hardware-tax-return-source.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { TaxReturnFiling, TaxReturnFinding, TaxReturnOperatorSalesPart, TaxReturnSourceAnswer, TaxReturnSourceRequest } from '@aglyn/aglyn/plugin-manager/plugin-tax-return-sources';
+import { type PosHardwareTaxJurisdiction, type PosHardwareTaxRowInput, type PosHardwareTaxSummary } from '../model/pos-hardware-tax-summary';
+/** The section's id, unique on the return. */
+export declare const POS_HARDWARE_TAX_SECTION_ID = "posHardware";
+/** The part the shop's online sales fold into the filing figures under. */
+export declare const POS_HARDWARE_SHOP_PART_ID = "posHardwareShop";
+/** The part an in-person sale at a store that is not the operator's own folds in under. */
+export declare const POS_HARDWARE_IN_PERSON_PART_ID = "posHardwareInPerson";
+/** Where an order is folded into the filing figures. */
+export type PosHardwareFoldedAs = 'shop' | 'store register sale' | 'in-person record';
+/** Who decides where a record folds in: the operator's own stores, by site id. */
+export interface PosHardwareFoldOptions {
+    /** The sites of the operator's own stores, whose register sales the own-stores section folds in. */
+    ownHostIds?: ReadonlySet<string>;
+}
+/** Where one retained sale record folds into the filing figures. See the module note. */
+export declare function posHardwareFoldedAs(row: Pick<PosHardwareTaxRowInput, 'source' | 'posHostId'>, options?: PosHardwareFoldOptions): PosHardwareFoldedAs;
+/**
+ * The operator's own hardware sales the filing figures fold in from this
+ * section: the shop's online sales, and any in-person sale whose store is not
+ * the operator's own. Every figure is the summary's own math over that part's
+ * records, so the card and the figures cannot disagree.
+ */
+export declare function posHardwareOperatorSales(rows: readonly PosHardwareTaxRowInput[], period: {
+    start: Date;
+    end: Date;
+}, options?: PosHardwareFoldOptions): TaxReturnOperatorSalesPart[];
+/** One order as the working papers carry it: amounts and the region, no buyer. */
+export interface PosHardwareTaxRow {
+    orderId: string;
+    paidAt: string | null;
+    status: string | null;
+    state: string | null;
+    country: string | null;
+    totalSalesCents: number;
+    taxableSalesCents: number | null;
+    taxCents: number;
+    refundedCents: number;
+    refundedAt: string | null;
+    /** How the order counts in this period. */
+    inPeriodAs: 'sale' | 'refund' | 'sale and refund';
+    /** Where it is folded into the filing figures. */
+    foldedAs: PosHardwareFoldedAs;
+}
+/** The filing jurisdiction's hardware figures, or zeros when none sold there. */
+export declare function posHardwareFilingFigures(summary: PosHardwareTaxSummary, filing: TaxReturnFiling): PosHardwareTaxJurisdiction;
+/** The section's findings. The platform raises the non-zero ones. */
+export declare function posHardwareTaxFindings(summary: PosHardwareTaxSummary, filing: TaxReturnFiling, operatorSales?: readonly TaxReturnOperatorSalesPart[]): TaxReturnFinding[];
+/** One ship-to state's row, ready to print. */
+export interface PosHardwareJurisdictionRow {
+    jurisdiction: string;
+    isFilingJurisdiction: boolean;
+    orders: number;
+    totalSalesCents: number;
+    taxableSalesCents: number;
+    taxCollectedCents: number;
+    refundedOrders: number;
+    refundedSalesCents: number;
+    refundedTaxCents: number;
+}
+/** Every ship-to state, the filing jurisdiction first, then by sales. */
+export declare function posHardwareJurisdictionRows(summary: PosHardwareTaxSummary, filing: TaxReturnFiling): PosHardwareJurisdictionRow[];
+/**
+ * The hardware section for one period, from records already read. Pure, so
+ * the section a preparer reads can be proved from fixtures.
+ */
+export declare function posHardwareTaxReturnAnswer(read: {
+    rows: readonly PosHardwareTaxRowInput[];
+    truncated: boolean;
+    undatedRows: number;
+}, request: TaxReturnSourceRequest, options?: PosHardwareFoldOptions): TaxReturnSourceAnswer;
+/**
+ * Reads the period's hardware records and answers for them.
+ *
+ * Three range queries, because a record counts in a period two ways — paid
+ * in it, or refunded in it (by the stamp of the status that refunded it) —
+ * and a fourth, the honesty check: a range query cannot match a record whose
+ * `paidAtMs` is null, so those are counted over all of them and the platform
+ * blocks the return on any. Each is a single-field range, served by
+ * Firestore's automatic index. A query that reaches the row cap marks the
+ * section truncated, and the platform blocks on that too.
+ */
+export declare function readPosHardwareTaxReturn(request: TaxReturnSourceRequest, options?: PosHardwareFoldOptions): Promise<TaxReturnSourceAnswer>;