@aglyn/plugins-commerce 1.0.0-beta.232 → 1.0.0-beta.234

package/src/lib/model/commerce-pos-kiosk.d.ts

@@ -0,0 +1,175 @@
+/**
+ * @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 PosReceiptChannel } from './commerce-pos';
+import type { ModifierSelection, ProductModifierGroup } from './product-modifiers';
+/** Which kind of paired screen a device token opens. */
+export type PosDeviceMode = 'display' | 'kiosk';
+/** A product as the kiosk grid shows it: no cost, no stock count, no supplier. */
+export interface PosKioskProduct {
+    id: string;
+    name: string;
+    description?: string;
+    imageUrl?: string;
+    categoryIds: string[];
+    /** The product's option axes ("Size": S, M, L), for the variant picker. */
+    options: Array<{
+        name: string;
+        values: string[];
+    }>;
+    variants: PosKioskVariant[];
+    modifierGroups: ProductModifierGroup[];
+}
+export interface PosKioskVariant {
+    id: string;
+    /** Option selections keyed by option name; empty for the default variant. */
+    options: Record<string, string>;
+    priceCents: number;
+    /** A tracked variant at or below zero whose product refuses to oversell. */
+    soldOut: boolean;
+}
+export interface PosKioskCategory {
+    id: string;
+    name: string;
+}
+export interface PosKioskCatalog {
+    products: PosKioskProduct[];
+    categories: PosKioskCategory[];
+    /** The store's currency, lower case (`usd`). */
+    currency: string;
+}
+/** What the kiosk offers, resolved on the server for one paired register. */
+export interface PosKioskContext {
+    branding: {
+        name: string;
+        logoUrl: string | null;
+        logoDarkUrl: string | null;
+        message: string;
+    };
+    currency: string;
+    tipping: {
+        enabled: boolean;
+        percentages: number[];
+    };
+    payments: {
+        /** A Stripe Terminal smart reader is assigned to this register. */
+        reader: boolean;
+        /** Card-present payments are switched on for the platform (Tap to Pay needs the native app too). */
+        cardPresent: boolean;
+        /** "Pay at counter" sends the order to the register's queue. */
+        payAtCounter: boolean;
+    };
+    receipts: PosReceiptChannel[];
+    offerMarketing: boolean;
+    /** Seconds without a touch before the kiosk asks "Still there?". */
+    idleSeconds: number;
+    /** Stripe test mode: a test card can be tapped from the payment screen. */
+    testMode: boolean;
+}
+/** One cart line as the kiosk sends it: ids and a count, never a price. */
+export interface PosKioskLine {
+    productId: string;
+    variantId?: string;
+    quantity: number;
+    modifiers?: ModifierSelection[];
+}
+/** A line of a priced kiosk order, as the customer's screen shows it. */
+export interface PosKioskSaleLine {
+    name: string;
+    variantLabel?: string;
+    quantity: number;
+    amountCents: number;
+}
+export type PosKioskSaleStatus = 
+/** Priced and waiting for a card at the kiosk. */
+'open'
+/** Sent to the register's queue; a cashier takes payment. */
+ | 'queued' | 'paid' | 'voided';
+/** A kiosk order as its own screen reads it back. */
+export interface PosKioskSale {
+    orderId: string;
+    /** The order number the customer is called by. */
+    number: number;
+    status: PosKioskSaleStatus;
+    lines: PosKioskSaleLine[];
+    itemsCents: number;
+    discountCents: number;
+    taxCents: number;
+    totalCents: number;
+    tipCents: number;
+    paidCents: number;
+    dueCents: number;
+    /** The card payment in flight, if any. */
+    payment: {
+        id: string;
+        status: string;
+        failureMessage?: string;
+    } | null;
+}
+/** Seconds without a touch before the kiosk asks "Still there?", by default. */
+export declare const POS_KIOSK_IDLE_SECONDS_DEFAULT = 90;
+export declare const POS_KIOSK_IDLE_SECONDS_MIN = 30;
+export declare const POS_KIOSK_IDLE_SECONDS_MAX = 600;
+/** How long "Still there?" waits before the kiosk clears itself. */
+export declare const POS_KIOSK_IDLE_WARNING_SECONDS = 20;
+/** The order-number screen returns to the start after this long. */
+export declare const POS_KIOSK_DONE_SECONDS = 15;
+/** Most lines one kiosk order carries. */
+export declare const POS_KIOSK_MAX_LINES = 40;
+/** Most of one line a customer may order at a kiosk. */
+export declare const POS_KIOSK_MAX_QUANTITY = 20;
+/** Most products the kiosk grid lists in one category. */
+export declare const POS_KIOSK_CATALOG_LIMIT = 200;
+/** Wrong staff PINs a kiosk takes before it locks its unlock screen. */
+export declare const POS_KIOSK_UNLOCK_MAX_ATTEMPTS = 5;
+/** How long a kiosk's unlock screen stays locked after too many wrong PINs. */
+export declare const POS_KIOSK_UNLOCK_LOCKOUT_MS: number;
+/** How long a staff unlock keeps the kiosk's settings open. */
+export declare const POS_KIOSK_UNLOCK_TTL_MS: number;
+/**
+ * The cart as the kiosk may send it, or why not. Ids are shape-checked and
+ * quantities bounded here; everything else — whether the product exists, is
+ * for sale, what it costs and whether its modifiers are valid — is the sale
+ * route's to decide from the product documents.
+ */
+export declare function sanitizePosKioskLines(raw: unknown): {
+    ok: true;
+    lines: PosKioskLine[];
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The tip a kiosk customer chose, recomputed from the server's own figure
+ * for what is being paid: a percentage only from the store's presets, a
+ * custom amount bounded like every register tip. Null when the choice is
+ * not one the store offers.
+ */
+export declare function posKioskTipCents(choice: unknown, input: {
+    baseCents: number;
+    enabled: boolean;
+    percentages: readonly number[];
+    percent?: unknown;
+    cents?: unknown;
+}): number | null;
+/** The idle timeout a merchant set, bounded. */
+export declare function posKioskIdleSeconds(raw: unknown): number;
+/**
+ * The kiosk's estimate of its cart, from the catalog prices it was given —
+ * shown while the customer shops and never sent. The order is priced again,
+ * with tax, by the server when they check out.
+ */
+export declare function posKioskEstimateCents(lines: readonly PosKioskLine[], products: readonly PosKioskProduct[]): number;

package/src/lib/model/commerce-pos-kiosk.js

@@ -0,0 +1,147 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 { posTipFromPercent, posTipProblem } from "./commerce-pos.js";
+/** Seconds without a touch before the kiosk asks "Still there?", by default. */ export const POS_KIOSK_IDLE_SECONDS_DEFAULT = 90;
+export const POS_KIOSK_IDLE_SECONDS_MIN = 30;
+export const POS_KIOSK_IDLE_SECONDS_MAX = 600;
+/** How long "Still there?" waits before the kiosk clears itself. */ export const POS_KIOSK_IDLE_WARNING_SECONDS = 20;
+/** The order-number screen returns to the start after this long. */ export const POS_KIOSK_DONE_SECONDS = 15;
+/** Most lines one kiosk order carries. */ export const POS_KIOSK_MAX_LINES = 40;
+/** Most of one line a customer may order at a kiosk. */ export const POS_KIOSK_MAX_QUANTITY = 20;
+/** Most products the kiosk grid lists in one category. */ export const POS_KIOSK_CATALOG_LIMIT = 200;
+/** Wrong staff PINs a kiosk takes before it locks its unlock screen. */ export const POS_KIOSK_UNLOCK_MAX_ATTEMPTS = 5;
+/** How long a kiosk's unlock screen stays locked after too many wrong PINs. */ export const POS_KIOSK_UNLOCK_LOCKOUT_MS = 15 * 60 * 1000;
+/** How long a staff unlock keeps the kiosk's settings open. */ export const POS_KIOSK_UNLOCK_TTL_MS = 5 * 60 * 1000;
+const ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+/**
+ * The cart as the kiosk may send it, or why not. Ids are shape-checked and
+ * quantities bounded here; everything else — whether the product exists, is
+ * for sale, what it costs and whether its modifiers are valid — is the sale
+ * route's to decide from the product documents.
+ */ export function sanitizePosKioskLines(raw) {
+    if (!Array.isArray(raw) || raw.length === 0) return {
+        ok: false,
+        error: 'Your cart is empty.'
+    };
+    if (raw.length > POS_KIOSK_MAX_LINES) {
+        return {
+            ok: false,
+            error: `An order can have at most ${POS_KIOSK_MAX_LINES} items.`
+        };
+    }
+    const lines = [];
+    for (const entry of raw){
+        var _ref;
+        const productId = String((_ref = entry == null ? void 0 : entry['productId']) != null ? _ref : '');
+        const variantId = (entry == null ? void 0 : entry['variantId']) == null ? '' : String(entry['variantId']);
+        const quantity = Number(entry == null ? void 0 : entry['quantity']);
+        if (!ID_PATTERN.test(productId) || variantId && !ID_PATTERN.test(variantId)) {
+            return {
+                ok: false,
+                error: 'An item in your cart is no longer available.'
+            };
+        }
+        if (!Number.isInteger(quantity) || quantity < 1 || quantity > POS_KIOSK_MAX_QUANTITY) {
+            return {
+                ok: false,
+                error: `Order 1 to ${POS_KIOSK_MAX_QUANTITY} of each item.`
+            };
+        }
+        const rawModifiers = Array.isArray(entry == null ? void 0 : entry['modifiers']) ? entry['modifiers'] : [];
+        if (rawModifiers.length > 200) return {
+            ok: false,
+            error: 'Too many choices on one item.'
+        };
+        const modifiers = [];
+        for (const pick of rawModifiers){
+            var _ref1, _ref2;
+            const groupId = String((_ref1 = pick == null ? void 0 : pick['groupId']) != null ? _ref1 : '');
+            const optionId = String((_ref2 = pick == null ? void 0 : pick['optionId']) != null ? _ref2 : '');
+            if (!ID_PATTERN.test(groupId) || !ID_PATTERN.test(optionId)) {
+                return {
+                    ok: false,
+                    error: 'A choice on an item is no longer offered.'
+                };
+            }
+            modifiers.push({
+                groupId,
+                optionId
+            });
+        }
+        lines.push(_extends({
+            productId
+        }, variantId ? {
+            variantId
+        } : {}, {
+            quantity
+        }, modifiers.length ? {
+            modifiers
+        } : {}));
+    }
+    return {
+        ok: true,
+        lines
+    };
+}
+/**
+ * The tip a kiosk customer chose, recomputed from the server's own figure
+ * for what is being paid: a percentage only from the store's presets, a
+ * custom amount bounded like every register tip. Null when the choice is
+ * not one the store offers.
+ */ export function posKioskTipCents(choice, input) {
+    if (choice === undefined || choice === null || choice === 'none') return 0;
+    if (!input.enabled) return null;
+    if (choice === 'percent') {
+        const percent = Math.round(Number(input.percent));
+        if (!input.percentages.includes(percent)) return null;
+        return posTipFromPercent(input.baseCents, percent);
+    }
+    if (choice === 'custom') {
+        const cents = Math.round(Number(input.cents));
+        return posTipProblem(cents, input.baseCents) ? null : cents;
+    }
+    return null;
+}
+/** The idle timeout a merchant set, bounded. */ export function posKioskIdleSeconds(raw) {
+    const value = Math.round(Number(raw));
+    if (!Number.isFinite(value) || value <= 0) return POS_KIOSK_IDLE_SECONDS_DEFAULT;
+    return Math.min(POS_KIOSK_IDLE_SECONDS_MAX, Math.max(POS_KIOSK_IDLE_SECONDS_MIN, value));
+}
+/**
+ * The kiosk's estimate of its cart, from the catalog prices it was given —
+ * shown while the customer shops and never sent. The order is priced again,
+ * with tax, by the server when they check out.
+ */ export function posKioskEstimateCents(lines, products) {
+    let total = 0;
+    for (const line of lines){
+        var _product_variants_find, _line_modifiers;
+        const product = products.find((candidate)=>candidate.id === line.productId);
+        if (!product) continue;
+        const variant = (_product_variants_find = product.variants.find((candidate)=>candidate.id === line.variantId)) != null ? _product_variants_find : product.variants[0];
+        if (!variant) continue;
+        const extra = ((_line_modifiers = line.modifiers) != null ? _line_modifiers : []).reduce((sum, pick)=>{
+            var _ref;
+            const group = product.modifierGroups.find((candidate)=>candidate.id === pick.groupId);
+            const option = group == null ? void 0 : group.options.find((candidate)=>candidate.id === pick.optionId);
+            return sum + ((_ref = option == null ? void 0 : option.priceCents) != null ? _ref : 0);
+        }, 0);
+        total += (variant.priceCents + extra) * line.quantity;
+    }
+    return total;
+}
+
+//# sourceMappingURL=commerce-pos-kiosk.js.map

package/src/lib/model/commerce-pos-kiosk.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/commerce-pos-kiosk.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 { posTipFromPercent, posTipProblem, type PosReceiptChannel } from './commerce-pos'\nimport type { ModifierSelection, ProductModifierGroup } from './product-modifiers'\n\n/*==========================================\n * THE SELF-SERVICE KIOSK (AGL-3623).\n *\n * A register's second kind of paired screen: where the customer display\n * (AGL-3608) mirrors the cashier's basket, a kiosk lets the customer build\n * their own order — a product grid with categories and modifiers, a cart, a\n * tip, payment on the register's card reader or Tap to Pay, or \"pay at\n * counter\", which sends the order to the register's queue for a cashier.\n *\n * It pairs exactly like a display (the same six-digit code and the same\n * hashed device token, with `mode: 'kiosk'` on both), and it never holds a\n * staff session: every request carries the device token and the server\n * prices everything. These are the shapes the kiosk route and every client\n * of it — the web kiosk and the native POS app — agree on.\n *=========================================*/\n\n/** Which kind of paired screen a device token opens. */\nexport type PosDeviceMode = 'display' | 'kiosk'\n\n/** A product as the kiosk grid shows it: no cost, no stock count, no supplier. */\nexport interface PosKioskProduct {\n  id: string\n  name: string\n  description?: string\n  imageUrl?: string\n  categoryIds: string[]\n  /** The product's option axes (\"Size\": S, M, L), for the variant picker. */\n  options: Array<{ name: string; values: string[] }>\n  variants: PosKioskVariant[]\n  modifierGroups: ProductModifierGroup[]\n}\n\nexport interface PosKioskVariant {\n  id: string\n  /** Option selections keyed by option name; empty for the default variant. */\n  options: Record<string, string>\n  priceCents: number\n  /** A tracked variant at or below zero whose product refuses to oversell. */\n  soldOut: boolean\n}\n\nexport interface PosKioskCategory {\n  id: string\n  name: string\n}\n\nexport interface PosKioskCatalog {\n  products: PosKioskProduct[]\n  categories: PosKioskCategory[]\n  /** The store's currency, lower case (`usd`). */\n  currency: string\n}\n\n/** What the kiosk offers, resolved on the server for one paired register. */\nexport interface PosKioskContext {\n  branding: {\n    name: string\n    logoUrl: string | null\n    logoDarkUrl: string | null\n    message: string\n  }\n  currency: string\n  tipping: { enabled: boolean; percentages: number[] }\n  payments: {\n    /** A Stripe Terminal smart reader is assigned to this register. */\n    reader: boolean\n    /** Card-present payments are switched on for the platform (Tap to Pay needs the native app too). */\n    cardPresent: boolean\n    /** \"Pay at counter\" sends the order to the register's queue. */\n    payAtCounter: boolean\n  }\n  receipts: PosReceiptChannel[]\n  offerMarketing: boolean\n  /** Seconds without a touch before the kiosk asks \"Still there?\". */\n  idleSeconds: number\n  /** Stripe test mode: a test card can be tapped from the payment screen. */\n  testMode: boolean\n}\n\n/** One cart line as the kiosk sends it: ids and a count, never a price. */\nexport interface PosKioskLine {\n  productId: string\n  variantId?: string\n  quantity: number\n  modifiers?: ModifierSelection[]\n}\n\n/** A line of a priced kiosk order, as the customer's screen shows it. */\nexport interface PosKioskSaleLine {\n  name: string\n  variantLabel?: string\n  quantity: number\n  amountCents: number\n}\n\nexport type PosKioskSaleStatus =\n  /** Priced and waiting for a card at the kiosk. */\n  | 'open'\n  /** Sent to the register's queue; a cashier takes payment. */\n  | 'queued'\n  | 'paid'\n  | 'voided'\n\n/** A kiosk order as its own screen reads it back. */\nexport interface PosKioskSale {\n  orderId: string\n  /** The order number the customer is called by. */\n  number: number\n  status: PosKioskSaleStatus\n  lines: PosKioskSaleLine[]\n  itemsCents: number\n  discountCents: number\n  taxCents: number\n  totalCents: number\n  tipCents: number\n  paidCents: number\n  dueCents: number\n  /** The card payment in flight, if any. */\n  payment: { id: string; status: string; failureMessage?: string } | null\n}\n\n/** Seconds without a touch before the kiosk asks \"Still there?\", by default. */\nexport const POS_KIOSK_IDLE_SECONDS_DEFAULT = 90\nexport const POS_KIOSK_IDLE_SECONDS_MIN = 30\nexport const POS_KIOSK_IDLE_SECONDS_MAX = 600\n\n/** How long \"Still there?\" waits before the kiosk clears itself. */\nexport const POS_KIOSK_IDLE_WARNING_SECONDS = 20\n\n/** The order-number screen returns to the start after this long. */\nexport const POS_KIOSK_DONE_SECONDS = 15\n\n/** Most lines one kiosk order carries. */\nexport const POS_KIOSK_MAX_LINES = 40\n\n/** Most of one line a customer may order at a kiosk. */\nexport const POS_KIOSK_MAX_QUANTITY = 20\n\n/** Most products the kiosk grid lists in one category. */\nexport const POS_KIOSK_CATALOG_LIMIT = 200\n\n/** Wrong staff PINs a kiosk takes before it locks its unlock screen. */\nexport const POS_KIOSK_UNLOCK_MAX_ATTEMPTS = 5\n\n/** How long a kiosk's unlock screen stays locked after too many wrong PINs. */\nexport const POS_KIOSK_UNLOCK_LOCKOUT_MS = 15 * 60 * 1000\n\n/** How long a staff unlock keeps the kiosk's settings open. */\nexport const POS_KIOSK_UNLOCK_TTL_MS = 5 * 60 * 1000\n\nconst ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/\n\n/**\n * The cart as the kiosk may send it, or why not. Ids are shape-checked and\n * quantities bounded here; everything else — whether the product exists, is\n * for sale, what it costs and whether its modifiers are valid — is the sale\n * route's to decide from the product documents.\n */\nexport function sanitizePosKioskLines(\n  raw: unknown,\n): { ok: true; lines: PosKioskLine[] } | { ok: false; error: string } {\n  if (!Array.isArray(raw) || raw.length === 0) return { ok: false, error: 'Your cart is empty.' }\n  if (raw.length > POS_KIOSK_MAX_LINES) {\n    return { ok: false, error: `An order can have at most ${POS_KIOSK_MAX_LINES} items.` }\n  }\n  const lines: PosKioskLine[] = []\n  for (const entry of raw as Array<Record<string, unknown>>) {\n    const productId = String(entry?.['productId'] ?? '')\n    const variantId = entry?.['variantId'] == null ? '' : String(entry['variantId'])\n    const quantity = Number(entry?.['quantity'])\n    if (!ID_PATTERN.test(productId) || (variantId && !ID_PATTERN.test(variantId))) {\n      return { ok: false, error: 'An item in your cart is no longer available.' }\n    }\n    if (!Number.isInteger(quantity) || quantity < 1 || quantity > POS_KIOSK_MAX_QUANTITY) {\n      return { ok: false, error: `Order 1 to ${POS_KIOSK_MAX_QUANTITY} of each item.` }\n    }\n    const rawModifiers = Array.isArray(entry?.['modifiers']) ? (entry['modifiers'] as unknown[]) : []\n    if (rawModifiers.length > 200) return { ok: false, error: 'Too many choices on one item.' }\n    const modifiers: ModifierSelection[] = []\n    for (const pick of rawModifiers as Array<Record<string, unknown>>) {\n      const groupId = String(pick?.['groupId'] ?? '')\n      const optionId = String(pick?.['optionId'] ?? '')\n      if (!ID_PATTERN.test(groupId) || !ID_PATTERN.test(optionId)) {\n        return { ok: false, error: 'A choice on an item is no longer offered.' }\n      }\n      modifiers.push({ groupId, optionId })\n    }\n    lines.push({\n      productId,\n      ...(variantId ? { variantId } : {}),\n      quantity,\n      ...(modifiers.length ? { modifiers } : {}),\n    })\n  }\n  return { ok: true, lines }\n}\n\n/**\n * The tip a kiosk customer chose, recomputed from the server's own figure\n * for what is being paid: a percentage only from the store's presets, a\n * custom amount bounded like every register tip. Null when the choice is\n * not one the store offers.\n */\nexport function posKioskTipCents(\n  choice: unknown,\n  input: { baseCents: number; enabled: boolean; percentages: readonly number[]; percent?: unknown; cents?: unknown },\n): number | null {\n  if (choice === undefined || choice === null || choice === 'none') return 0\n  if (!input.enabled) return null\n  if (choice === 'percent') {\n    const percent = Math.round(Number(input.percent))\n    if (!input.percentages.includes(percent)) return null\n    return posTipFromPercent(input.baseCents, percent)\n  }\n  if (choice === 'custom') {\n    const cents = Math.round(Number(input.cents))\n    return posTipProblem(cents, input.baseCents) ? null : cents\n  }\n  return null\n}\n\n/** The idle timeout a merchant set, bounded. */\nexport function posKioskIdleSeconds(raw: unknown): number {\n  const value = Math.round(Number(raw))\n  if (!Number.isFinite(value) || value <= 0) return POS_KIOSK_IDLE_SECONDS_DEFAULT\n  return Math.min(POS_KIOSK_IDLE_SECONDS_MAX, Math.max(POS_KIOSK_IDLE_SECONDS_MIN, value))\n}\n\n/**\n * The kiosk's estimate of its cart, from the catalog prices it was given —\n * shown while the customer shops and never sent. The order is priced again,\n * with tax, by the server when they check out.\n */\nexport function posKioskEstimateCents(\n  lines: readonly PosKioskLine[],\n  products: readonly PosKioskProduct[],\n): number {\n  let total = 0\n  for (const line of lines) {\n    const product = products.find((candidate) => candidate.id === line.productId)\n    if (!product) continue\n    const variant =\n      product.variants.find((candidate) => candidate.id === line.variantId) ?? product.variants[0]\n    if (!variant) continue\n    const extra = (line.modifiers ?? []).reduce((sum, pick) => {\n      const group = product.modifierGroups.find((candidate) => candidate.id === pick.groupId)\n      const option = group?.options.find((candidate) => candidate.id === pick.optionId)\n      return sum + (option?.priceCents ?? 0)\n    }, 0)\n    total += (variant.priceCents + extra) * line.quantity\n  }\n  return total\n}\n"],"names":["posTipFromPercent","posTipProblem","POS_KIOSK_IDLE_SECONDS_DEFAULT","POS_KIOSK_IDLE_SECONDS_MIN","POS_KIOSK_IDLE_SECONDS_MAX","POS_KIOSK_IDLE_WARNING_SECONDS","POS_KIOSK_DONE_SECONDS","POS_KIOSK_MAX_LINES","POS_KIOSK_MAX_QUANTITY","POS_KIOSK_CATALOG_LIMIT","POS_KIOSK_UNLOCK_MAX_ATTEMPTS","POS_KIOSK_UNLOCK_LOCKOUT_MS","POS_KIOSK_UNLOCK_TTL_MS","ID_PATTERN","sanitizePosKioskLines","raw","Array","isArray","length","ok","error","lines","entry","productId","String","variantId","quantity","Number","test","isInteger","rawModifiers","modifiers","pick","groupId","optionId","push","posKioskTipCents","choice","input","undefined","enabled","percent","Math","round","percentages","includes","baseCents","cents","posKioskIdleSeconds","value","isFinite","min","max","posKioskEstimateCents","products","total","line","product","find","candidate","id","variant","variants","extra","reduce","sum","group","modifierGroups","option","options","priceCents"],"mappings":"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"}

package/src/lib/model/commerce-pos-offline.d.ts

@@ -0,0 +1,234 @@
+/**
+ * @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 OrderTotals } from './commerce-orders';
+import type { ModifierSelection } from './product-modifiers';
+/** The route both register clients sync through. */
+export declare const POS_OFFLINE_SYNC_ROUTE = "/api/commerce/pos-offline-sync";
+/** The most sales one sync request carries; a longer queue sends in batches. */
+export declare const POS_OFFLINE_SYNC_BATCH_MAX = 25;
+/** Lines one offline sale may carry, the same bound the register's basket has. */
+export declare const POS_OFFLINE_SALE_MAX_LINES = 100;
+/** A sale synced later than this after it was rung is flagged `late-sync`. */
+export declare const POS_OFFLINE_LATE_SYNC_MS: number;
+/**
+ * How far back a sale's own clock is believed. Older, and the server stamps
+ * the sale at this bound and flags it, rather than letting a device clock
+ * place a sale anywhere in history.
+ */
+export declare const POS_OFFLINE_MAX_AGE_MS: number;
+/** How far ahead of the server a device clock may run before it is clamped. */
+export declare const POS_OFFLINE_CLOCK_SKEW_MS: number;
+/** The one tender an offline sale takes. */
+export type PosOfflineTender = 'cash';
+/** Every tender the register turns off while offline, and why, in its words. */
+export declare const POS_OFFLINE_DISABLED_TENDERS: Readonly<Record<string, string>>;
+/** One basket line as the register rang it. */
+export interface PosOfflineSaleLine {
+    productId: string;
+    variantId?: string;
+    name: string;
+    /** Variant options and modifier choices, as the receipt printed them. */
+    variantLabel?: string;
+    sku?: string;
+    productType?: 'physical' | 'digital' | 'service';
+    quantity: number;
+    /** Per unit, modifiers included, from the cached catalog. */
+    unitAmountCents: number;
+    modifiers?: ModifierSelection[];
+}
+/** The customer the register attached: only what the sale and its receipt need. */
+export interface PosOfflineSaleCustomer {
+    email?: string;
+    name?: string;
+    kind?: string;
+    id?: string;
+}
+/** One sale rung while offline, exactly as the register queued it. */
+export interface PosOfflineSale {
+    v: 1;
+    /** The register's key for this sale, minted once; the order's id on the server. */
+    saleKey: string;
+    hostId: string;
+    /** The workspace the register was signed in to. */
+    orgId: string;
+    /** Who was signed in on the device: the only member who may sync it. */
+    signedInUid: string;
+    registerId: string;
+    /** The shift open on the register when the sale was rung. */
+    shiftId?: string | null;
+    locationId?: string;
+    /** A PIN-switched cashier's assertion, valid when the sale was rung. */
+    cashierAssertion?: string;
+    /** The device's clock when the cash was taken. */
+    soldAtMs: number;
+    lines: PosOfflineSaleLine[];
+    /** The cashier's discount, a percentage of the goods. */
+    discountPct: number;
+    /** The totals the receipt printed and the customer paid. */
+    totals: OrderTotals;
+    cashTenderedCents: number;
+    changeCents: number;
+    customer?: PosOfflineSaleCustomer;
+}
+/** What does not match, said on the order and back to the register. */
+export type PosOfflineFlag = 'price-changed' | 'unknown-product' | 'tax-differs' | 'totals-restated' | 'discount-over-limit' | 'cash-short' | 'stock-short' | 'shift-closed' | 'no-shift' | 'unknown-register' | 'register-over-cap' | 'late-sync' | 'clock-adjusted' | 'cashier-unverified';
+/** Each flag in the words the order and the register show. */
+export declare const POS_OFFLINE_FLAG_LABELS: Record<PosOfflineFlag, string>;
+/** A line whose stock went short when the sale synced. */
+export interface PosOfflineStockConflict {
+    productId: string;
+    variantId?: string;
+    name: string;
+    /** Units sold. */
+    requested: number;
+    /** Units the shelf actually gave up. */
+    applied: number;
+    /** Units sold that the shelf did not hold. */
+    shortUnits: number;
+}
+/** What the order records about having been rung offline. */
+export interface PosOfflineOrderStamp {
+    saleKey: string;
+    /** The device's clock when the cash was taken. */
+    soldAtMs: number;
+    syncedAtMs: number;
+    /** Who synced it: always the member who was signed in when it was rung. */
+    syncedBy: string;
+    flags: PosOfflineFlag[];
+    stockConflicts?: PosOfflineStockConflict[];
+    /** The server's own price per line where it differed, for the merchant to compare. */
+    priceDrift?: Array<{
+        index: number;
+        rungCents: number;
+        currentCents: number;
+    }>;
+}
+/** Why a sale was refused, and whether the register should keep trying. */
+export type PosOfflineRefusal = 'wrong-staff' | 'wrong-site' | 'wrong-workspace' | 'invalid' | 'conflict' | 'failed';
+/** What became of one sale the register sent. */
+export type PosOfflineOutcomeStatus = 'recorded' | 'replayed' | 'refused';
+/**
+ * One sale's answer, in the order the request sent them. `recorded` and
+ * `replayed` carry the order; `refused` carries the reason, the sentence and
+ * whether to keep trying. One flat shape, so every register client — the web
+ * register and the native apps — decodes it the same way.
+ */
+export interface PosOfflineSaleOutcome {
+    saleKey: string;
+    status: PosOfflineOutcomeStatus;
+    orderId?: string;
+    number?: number | null;
+    flags?: PosOfflineFlag[];
+    stockConflicts?: PosOfflineStockConflict[];
+    reason?: PosOfflineRefusal;
+    error?: string;
+    /** Keep it queued and try again later (a transient failure). */
+    retry?: boolean;
+}
+export interface PosOfflineSyncRequest {
+    hostId: string;
+    sales: PosOfflineSale[];
+}
+export interface PosOfflineSyncResponse {
+    results: PosOfflineSaleOutcome[];
+}
+/** One register as the offline kit lists it. */
+export interface PosOfflineKitRegister {
+    id: string;
+    name: string;
+    locationId?: string;
+    openShiftId: string | null;
+}
+/**
+ * Everything a register needs to sell offline besides the catalog, from
+ * `GET /api/commerce/pos-offline-sync?hostId=`: the server's own answers, so
+ * the register and the sync agree about the rate and the rules.
+ */
+export interface PosOfflineKit {
+    v: 1;
+    hostId: string;
+    orgId: string;
+    issuedAtMs: number;
+    /** Offline selling is possible for this site right now. */
+    available: boolean;
+    /** Why not, in the cashier's words, when it is not. */
+    unavailableReason?: string;
+    /** The store's own in-person rate; `null` pct is no tax. */
+    tax: {
+        pct: number | null;
+        pricesIncludeTax: boolean;
+    };
+    maxDiscountPct: number;
+    requireOpenShift: boolean;
+    registers: PosOfflineKitRegister[];
+    /** What the receipt prints at its head and foot. `logo` is the stored value. */
+    receipt: {
+        name: string;
+        logo?: string;
+        address?: string;
+        footer?: string;
+        returnPolicy?: string;
+    };
+}
+/**
+ * The totals of an offline sale: the cashier's discount on the goods, then
+ * the store's in-person tax on what is left — exactly the arithmetic the
+ * online register's sale route uses for the same basket with no promotion.
+ * `pricesIncludeTax` adds nothing, as at the online till.
+ */
+export declare function posOfflineSaleTotals(input: {
+    lines: ReadonlyArray<Pick<PosOfflineSaleLine, 'unitAmountCents' | 'quantity'>>;
+    discountPct: number;
+    tax: {
+        pct: number | null;
+        pricesIncludeTax: boolean;
+    };
+}): OrderTotals;
+/** Change for cash handed over, never negative. */
+export declare function posOfflineChangeCents(totalCents: number, tenderedCents: number): number;
+/** A key the register minted: an id the order can take, and nothing else. */
+export declare function posOfflineSaleKeyIsValid(key: unknown): key is string;
+/**
+ * The sale's time as the server records it: the device's clock when it is
+ * believable, clamped to now when it runs ahead, and to the oldest believable
+ * moment when it claims to be older.
+ */
+export declare function posOfflineSoldAt(soldAtMs: number, nowMs: number): {
+    atMs: number;
+    adjusted: boolean;
+};
+/**
+ * A queued sale read off the wire, every field typed and bounded — or the
+ * sentence that says why it cannot be read at all. Pure, so the server and
+ * any client that wants to check its own queue answer the same.
+ */
+export declare function sanitizePosOfflineSale(raw: unknown): {
+    ok: true;
+    sale: PosOfflineSale;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Whether the register's totals are the arithmetic of its own lines: the
+ * goods are the lines' sum, the discount is the percentage of them, and the
+ * total is goods less discount plus the tax it rang. The tax itself is the
+ * register's, and checked against the store's rate separately.
+ */
+export declare function posOfflineTotalsAddUp(sale: Pick<PosOfflineSale, 'lines' | 'discountPct' | 'totals'>): boolean;
+/** The flags in the order and words the register lists them. */
+export declare function posOfflineFlagLabels(flags: readonly PosOfflineFlag[]): string[];