@classytic/pos-ui 0.1.0 → 1.2.0

package/dist/hardware/tauri-adapter.js

@@ -13,10 +13,17 @@ function getInvoke() {
 }
 var TauriReceiptPrinter = class {
 	async print(payload) {
-		await getInvoke()("printer_print", {
-			payload,
-			config: readPrinterConfig() ?? void 0
-		});
+		const invoke = getInvoke();
+		const config = readPrinterConfig() ?? void 0;
+		try {
+			await invoke("printer_print", {
+				payload,
+				config
+			});
+			return "confirmed";
+		} catch {
+			return "unknown";
+		}
 	}
 	async isAvailable() {
 		try {
@@ -28,7 +35,14 @@ var TauriReceiptPrinter = class {
 };
 var TauriCashDrawer = class {
 	async open() {
-		await getInvoke()("drawer_open", { config: readPrinterConfig() ?? void 0 });
+		const invoke = getInvoke();
+		const config = readPrinterConfig() ?? void 0;
+		try {
+			await invoke("drawer_open", { config });
+			return "confirmed";
+		} catch {
+			return "unknown";
+		}
 	}
 	async isAvailable() {
 		try {

package/dist/hardware/web-adapter.d.ts

@@ -1,15 +1,30 @@
-import { PosHardware } from "./ports.js";
-
+import { PosHardware, PrintOutcome } from "./ports.js";
 //#region src/hardware/web-adapter.d.ts
 /** DOM id of the rendered receipt — used by `printDocument` for print isolation. */
 declare const RECEIPT_DOM_ID = "pos-receipt";
+/**
+ * The browser `window.print()` path, factored out so it can ALSO be called
+ * directly as an explicit cashier-visible fallback after a failed/unknown
+ * agent print (see Stream 1.4: "not an automatic retry that might create a
+ * duplicate receipt" — the fallback is a deliberate second action, not
+ * something this file chains on its own).
+ */
+declare function printViaBrowserWindow(): Promise<PrintOutcome>;
 /**
  * Auto-detects the host: returns native Tauri adapters when the React
- * tree is running inside the `cashier-tauri` webview, otherwise returns
- * the browser stubs. Consumers stay agnostic — `<HardwareProvider>` in
- * `pos-shell.tsx` calls this once at mount and the same React tree
- * works on both surfaces with no per-component branching.
+ * tree is running inside the `cashier-tauri` webview; otherwise checks for a
+ * paired `@classytic/pos-agent` device (see `agent-pairing.ts`) and prefers
+ * it over the plain browser stubs. Consumers stay agnostic — `<HardwareProvider>`
+ * in `pos-shell.tsx` calls this once at mount and the same React tree works
+ * across all three surfaces with no per-component branching.
+ *
+ * This read is SYNCHRONOUS (`readAgentPairing()`, localStorage) because
+ * `createWebHardware()` runs inside `useMemo` and must return a stable object
+ * immediately — see the plan's Stream 1.4 on why adapter selection cannot be
+ * probed asynchronously at boot. `PosAgentReceiptPrinter`/`PosAgentCashDrawer`
+ * are cheap to construct (no eager network call); the actual agent request
+ * happens lazily inside `print()`/`open()`/`isAvailable()`.
  */
 declare function createWebHardware(): PosHardware;
 //#endregion
-export { RECEIPT_DOM_ID, createWebHardware };
+export { RECEIPT_DOM_ID, createWebHardware, printViaBrowserWindow };

package/dist/hardware/web-adapter.js

@@ -1,4 +1,6 @@
 import { createTauriHardware, isTauri } from "./tauri-adapter.js";
+import { readAgentPairing } from "./agent-pairing.js";
+import { PosAgentCashDrawer, PosAgentReceiptPrinter } from "./agent-adapter.js";
 import { printDocument } from "@classytic/fluid/client/core";
 
 //#region src/hardware/web-adapter.ts
@@ -22,21 +24,53 @@ import { printDocument } from "@classytic/fluid/client/core";
 */
 /** DOM id of the rendered receipt — used by `printDocument` for print isolation. */
 const RECEIPT_DOM_ID = "pos-receipt";
-var WebReceiptPrinter = class {
-	async print() {
-		if (typeof window === "undefined") throw new Error("WebReceiptPrinter requires a browser window");
+/**
+* The browser `window.print()` path, factored out so it can ALSO be called
+* directly as an explicit cashier-visible fallback after a failed/unknown
+* agent print (see Stream 1.4: "not an automatic retry that might create a
+* duplicate receipt" — the fallback is a deliberate second action, not
+* something this file chains on its own).
+*/
+async function printViaBrowserWindow() {
+	if (typeof window === "undefined") return "failed";
+	try {
 		printDocument(RECEIPT_DOM_ID);
+		return "confirmed";
+	} catch {
+		return "failed";
+	}
+}
+var WebCashDrawer = class {
+	async open() {
+		console.warn("[pos/hardware] Cash drawer kick is unavailable in the browser adapter. Pair a printer via POS settings or use the Tauri shell.");
+		return "failed";
 	}
 	async isAvailable() {
-		return typeof window !== "undefined";
+		return false;
 	}
 };
-var WebCashDrawer = class {
+var CompositeReceiptPrinter = class {
+	async print(payload, copyType) {
+		const pairing = readAgentPairing();
+		if (!pairing) return printViaBrowserWindow();
+		return new PosAgentReceiptPrinter(readAgentPairing, pairing.deviceId).print(payload, copyType);
+	}
+	async isAvailable() {
+		const pairing = readAgentPairing();
+		if (!pairing) return typeof window !== "undefined";
+		return new PosAgentReceiptPrinter(readAgentPairing, pairing.deviceId).isAvailable();
+	}
+};
+var CompositeCashDrawer = class {
 	async open() {
-		console.warn("[pos/hardware] Cash drawer kick is unavailable in the browser adapter. Install @classytic/pos-agent or use the Tauri shell.");
+		const pairing = readAgentPairing();
+		if (!pairing) return new WebCashDrawer().open();
+		return new PosAgentCashDrawer(readAgentPairing, pairing.deviceId).open();
 	}
 	async isAvailable() {
-		return false;
+		const pairing = readAgentPairing();
+		if (!pairing) return false;
+		return new PosAgentCashDrawer(readAgentPairing, pairing.deviceId).isAvailable();
 	}
 };
 var WebBarcodeScannerStub = class {
@@ -61,20 +95,28 @@ var WebPaymentTerminal = class {
 };
 /**
 * Auto-detects the host: returns native Tauri adapters when the React
-* tree is running inside the `cashier-tauri` webview, otherwise returns
-* the browser stubs. Consumers stay agnostic — `<HardwareProvider>` in
-* `pos-shell.tsx` calls this once at mount and the same React tree
-* works on both surfaces with no per-component branching.
+* tree is running inside the `cashier-tauri` webview; otherwise checks for a
+* paired `@classytic/pos-agent` device (see `agent-pairing.ts`) and prefers
+* it over the plain browser stubs. Consumers stay agnostic — `<HardwareProvider>`
+* in `pos-shell.tsx` calls this once at mount and the same React tree works
+* across all three surfaces with no per-component branching.
+*
+* This read is SYNCHRONOUS (`readAgentPairing()`, localStorage) because
+* `createWebHardware()` runs inside `useMemo` and must return a stable object
+* immediately — see the plan's Stream 1.4 on why adapter selection cannot be
+* probed asynchronously at boot. `PosAgentReceiptPrinter`/`PosAgentCashDrawer`
+* are cheap to construct (no eager network call); the actual agent request
+* happens lazily inside `print()`/`open()`/`isAvailable()`.
 */
 function createWebHardware() {
 	if (isTauri()) return createTauriHardware();
 	return {
-		printer: new WebReceiptPrinter(),
-		drawer: new WebCashDrawer(),
+		printer: new CompositeReceiptPrinter(),
+		drawer: new CompositeCashDrawer(),
 		scanner: new WebBarcodeScannerStub(),
 		terminal: new WebPaymentTerminal()
 	};
 }
 
 //#endregion
-export { RECEIPT_DOM_ID, createWebHardware };
+export { RECEIPT_DOM_ID, createWebHardware, printViaBrowserWindow };

package/dist/hooks/branch-scoped-key.js

@@ -0,0 +1,64 @@
+"use client";
+
+//#region src/hooks/branch-scoped-key.ts
+/**
+* Per-branch localStorage keys for the register — and the ONE rule about them:
+* **an unresolved branch is not a branch.**
+*
+* ## The bug this exists to make impossible
+*
+* `usePosCart` keyed its cart as `pos:cart:${branchId ?? "default"}` and
+* `usePosMultiOrder` did the same for parked sales. `branchId` is
+* `selectedBranch?.id`, so it is `undefined` for the first paint or two while the
+* branch context resolves — and every other consumer in these screens already
+* knows that (`{ enabled: !!branchId }`, `if (!branchId) return`). Only the
+* storage key invented a value.
+*
+* The result, observed on a real register: a cashier taps a membership, gets an
+* "Added to cart" toast, the line is written to `pos:cart:default`, and then the
+* branch resolves, the hook's key becomes `pos:cart:<branchId>`, and the cart
+* renders EMPTY. Nothing errored. The cashier re-rings the sale, or worse assumes
+* the till is broken mid-queue. `PaymentScreen` reads the same key, so the line
+* could not be paid for either.
+*
+* It is also a cross-branch leak in slow motion: `default` is shared by every
+* branch, so whatever survives there surfaces at whichever till loads next.
+*
+* This is the codebase's documented failure mode (AGENTS.md "FAIL LOUD", rule 1
+* and rule 3) in frontend clothing: a general fallback silently substituted for a
+* specific value that had not arrived yet, producing a plausible screen instead
+* of an error.
+*
+* ## Why a sentinel key rather than a conditional hook
+*
+* `useLocalStorage` needs a stable string key — a hook cannot be skipped. So an
+* unresolved branch gets `UNRESOLVED_BRANCH_KEY`, and **every mutator refuses to
+* write while that is the active key.** Nothing is ever stored under the
+* sentinel, which is what makes the loss impossible: there is no orphan to lose.
+* The window is under a second, and callers surface it (`ready === false`) rather
+* than accepting taps into the void.
+*/
+/**
+* The key used while the branch is unknown. Deliberately unusable: no mutator
+* writes to it, so it never accumulates state to be orphaned.
+*
+* `__` prefix so it cannot collide with a real branch id.
+*/
+const UNRESOLVED_BRANCH = "__unresolved__";
+/**
+* Build a branch-scoped storage key.
+*
+* A whitespace-only or empty `branchId` counts as unresolved: it would produce
+* `pos:cart:` and silently share one namespace across branches, which is the
+* same defect wearing a different value.
+*/
+function branchScopedKey(namespace, branchId) {
+	const resolved = typeof branchId === "string" && branchId.trim().length > 0;
+	return {
+		key: `${namespace}:${resolved ? branchId.trim() : UNRESOLVED_BRANCH}`,
+		ready: resolved
+	};
+}
+
+//#endregion
+export { UNRESOLVED_BRANCH, branchScopedKey };

package/dist/hooks/index.d.ts

@@ -0,0 +1,6 @@
+import { UsePosCartReturn, usePosCart } from "./usePosCart.js";
+import { UsePosCustomerReturn, usePosCustomer } from "./usePosCustomer.js";
+import { PaymentOption, SplitPaymentEntry, UsePosPaymentReturn, paymentNeedsReference, usePosPayment } from "./usePosPayment.js";
+import { ParkedOrder, UsePosMultiOrderReturn, usePosMultiOrder } from "./usePosMultiOrder.js";
+import { PosDeliveryAddress, PosDeliveryMethod, PosPaymentTerm, UsePosDeliveryReturn, usePosDelivery } from "./usePosDelivery.js";
+export { ParkedOrder, type PaymentOption, PosDeliveryAddress, PosDeliveryMethod, PosPaymentTerm, type SplitPaymentEntry, UsePosCartReturn, UsePosCustomerReturn, UsePosDeliveryReturn, UsePosMultiOrderReturn, UsePosPaymentReturn, paymentNeedsReference, usePosCart, usePosCustomer, usePosDelivery, usePosMultiOrder, usePosPayment };

package/dist/hooks/index.js

@@ -0,0 +1,7 @@
+import { usePosCart } from "./usePosCart.js";
+import { usePosCustomer } from "./usePosCustomer.js";
+import { usePosMultiOrder } from "./usePosMultiOrder.js";
+import { paymentNeedsReference, usePosPayment } from "./usePosPayment.js";
+import { usePosDelivery } from "./usePosDelivery.js";
+
+export { paymentNeedsReference, usePosCart, usePosCustomer, usePosDelivery, usePosMultiOrder, usePosPayment };

package/dist/hooks/sale-attempt.js

@@ -0,0 +1,62 @@
+//#region src/hooks/sale-attempt.ts
+/**
+* The sale-attempt key — what makes a retry a RETRY instead of a second sale.
+*
+* ## The bug this exists to make impossible
+*
+* `PaymentScreen` sent `idempotencyKey: generateIdempotencyKey()` inline in the
+* checkout payload. Every submit therefore carried a fresh UUID, which means the
+* server saw every submit as a distinct sale. The path that costs money:
+*
+*   cashier taps "Complete Sale" → request times out (the order COMMITTED, the
+*   response never arrived) → error toast → cashier taps again → new key → a
+*   second order, a second stock decrement, a second charge.
+*
+* Nothing errors. Both orders are valid. The drawer reconciles against two sales
+* that the customer paid for once. This is AGENTS.md FAIL LOUD rule 3 — absence
+* of an answer is not a negative answer — and the SDK docblock even warned that
+* "a random idempotency-key fallback defeats deduplication while looking
+* correctly wired."
+*
+* The server was never the problem. `packages/order`'s order model carries a
+* partial-unique index on `idempotencyKey` and `@spinekit/pos` passes it as the
+* placement's `winnerFilter`, so a repeated key replays the winning order rather
+* than creating another. That guarantee was fully built and simply never
+* reachable, because the client never sent the same key twice.
+*
+* ## The rule
+*
+* The key identifies the ATTEMPT — one cashier trying to close one cart — not
+* the HTTP call. So it must:
+*
+*   - be minted ONCE, when checkout starts;
+*   - SURVIVE a failure and a page reload (that is when retries happen);
+*   - be reused verbatim by every retry of that same sale;
+*   - be discarded only once the sale has actually succeeded.
+*
+* `usePosCart` binds that lifetime to branch-scoped storage and clears it in
+* `resetCart()` — which already is the "this sale is finished" boundary. The two
+* functions here are the pure part, split out so the rule is unit-testable
+* without a DOM.
+*/
+/** Mint a fresh attempt id. Prefixed so it is identifiable in server logs. */
+function newSaleAttemptId() {
+	if (typeof globalThis.crypto?.randomUUID === "function") return `pos_${globalThis.crypto.randomUUID()}`;
+	return `pos_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+/**
+* Reuse the stored attempt key if there is one, otherwise mint.
+*
+* The whole point is the FIRST branch: a stored key means an attempt is already
+* in flight or has already failed once, and reusing it is what lets the server
+* recognise the retry. Whitespace and `""` count as absent — a blank key
+* type-checks as a string and dedupes nothing, so treating it as present would
+* reinstate the bug with a value that merely looks set.
+*/
+function resolveSaleAttemptKey(stored, mint = newSaleAttemptId) {
+	if (typeof stored === "string" && stored.trim().length > 0) return stored.trim();
+	return mint();
+}
+
+//#endregion
+export { newSaleAttemptId, resolveSaleAttemptKey };

package/dist/hooks/useManagerAuth.js

@@ -2,6 +2,7 @@
 
 import { usePosAuth } from "../runtime/auth-port.js";
 import { useCallback, useState } from "react";
+import { presentError } from "@classytic/fluid/error-contract";
 import { useMutation } from "@tanstack/react-query";
 
 //#region src/hooks/useManagerAuth.ts
@@ -74,7 +75,14 @@ function useManagerAuth(options = {}) {
 		authorize,
 		clearAuth,
 		isPending: verifyMutation.isPending,
-		error: verifyMutation.error?.message || null,
+		/**
+		* A single line for `ManagerAuthDialog`'s banner, resolved through the
+		* shared error contract so a refusal the server CODED (a role denial) does
+		* not read the same as an unreachable network. The dialog has one text
+		* slot, so the presentation's `message` is the whole thing — it is written
+		* to stand alone without its title.
+		*/
+		error: verifyMutation.error ? presentError(verifyMutation.error, "Those credentials were not accepted.").message : null,
 		reset: verifyMutation.reset
 	};
 }

package/dist/hooks/usePosCart.d.ts

@@ -0,0 +1,55 @@
+import { PosCartItem as PosCartItem$1 } from "../dashboard/pos.types.js";
+import { PosProduct } from "@classytic/commerce-sdk/sales";
+//#region src/hooks/usePosCart.d.ts
+interface UsePosCartReturn {
+  cart: PosCartItem$1[];
+  membershipCardId: string;
+  pointsToRedeemInput: string;
+  discountInput: string;
+  setDiscountInput: (value: string) => void;
+  setMembershipCardId: (value: string) => void;
+  setPointsToRedeemInput: (value: string) => void;
+  addToCart: (product: PosProduct, variantSku?: string) => void;
+  /**
+   * Append a cashier-authored ad-hoc charge line to the cart (gift wrap,
+   * damaged-product reimbursement, custom handling).
+   *
+   * The label is what the cashier types; the system derives a
+   * slug-shaped `serviceCode` from it for reporting consistency
+   * (`Gift wrap` and `gift wrap` collapse to `gift-wrap`). `amountMajor`
+   * is in major units (matches `unitPrice` semantics on existing cart
+   * items); PaymentScreen converts to minor units at the order-create boundary.
+   */
+  addCharge: (label: string, amountMajor: number) => void;
+  updateQuantity: (index: number, delta: number) => void;
+  removeItem: (index: number) => void;
+  clearCart: () => void;
+  resetCart: () => void;
+  /** Replace the entire cart (used by resume-parked-order). */
+  replaceCart: (items: PosCartItem$1[]) => void;
+  /**
+   * The idempotency key for checking THIS cart out — minted on first call and
+   * then stable until `resetCart()`, which runs only after a sale succeeds.
+   *
+   * Call it at submit and send the result as `PosOrderPayload.idempotencyKey`.
+   * Because it is persisted per branch, a retry after a timeout — or after a
+   * reload — sends the SAME key, which is the only thing that lets the server's
+   * replay-the-winner index return the existing order instead of ringing a
+   * second sale. See `sale-attempt.ts` for the full account.
+   *
+   * Returns `null` while the branch is unresolved: an attempt cannot be scoped
+   * to a branch that does not exist yet, and minting into the sentinel namespace
+   * would produce a key that is discarded a moment later — which is the same
+   * defect wearing a different value.
+   */
+  beginSaleAttempt: () => string | null;
+  /**
+   * Is the cart bound to a resolved branch? While `false` every mutator refuses
+   * (see `branch-scoped-key.ts`) — gate the checkout affordance on it rather than
+   * letting a cashier discover it from an error toast.
+   */
+  ready: boolean;
+}
+declare function usePosCart(branchId?: string): UsePosCartReturn;
+//#endregion
+export { UsePosCartReturn, usePosCart };