Offline-first POS, part 3: selling with the router unplugged

import { db } from "../db/schema";
import { newId } from "../../shared/id";
import { printReceipt } from "../printing/receipt";
import { scheduleSync } from "../sync/worker";

/**
 * Completes a sale. Deliberately does NOT await the network.
 *
 * Order matters: persist, then print, then attempt sync. If the browser dies
 * between any two steps the sale still exists, and the outbox will find it on
 * next launch.
 */
export async function completeSale(input: {
  lines: { productId: string; quantity: number; unitPriceCents: number }[];
  paymentMethod: "cash" | "khqr" | "card";
  cashierId: string;
  deviceId: string;
}) {
  const subtotal = input.lines.reduce(
    (sum, l) => sum + l.unitPriceCents * l.quantity,
    0,
  );

  const sale = {
    id: newId(),
    occurredAt: new Date().toISOString(),
    subtotalCents: subtotal,
    totalCents: subtotal,
    // Cash offline is genuinely paid — the money is in the drawer. KHQR is not
    // verifiable without a connection, so it stays pending. Part 5 covers this.
    paymentState:
      input.paymentMethod === "cash" ? "paid" : "pending_verification",
    synced: 0,
    ...input,
  } as const;

  // 1. Persist. One transaction across both stores so a crash cannot leave a
  //    sale that nothing will ever send.
  const tx = db.transaction(["sales", "outbox"], "readwrite");
  await Promise.all([
    tx.objectStore("sales").add(sale),
    tx.objectStore("outbox").add({
      saleId: sale.id,
      attempts: 0,
      lastAttemptAt: null,
    }),
    tx.done,
  ]);

  // 2. Print. Local, no network involved.
  await printReceipt(sale);

  // 3. Try to sync — fire and forget. Failure is normal, not exceptional.
  void scheduleSync();

  return sale;
}

/**
 * Server level at last sync, minus everything sold on this device since.
 *
 * Deliberately called an estimate. A till that displays a confident number it
 * cannot possibly know teaches cashiers to distrust the whole screen the first
 * time it is wrong.
 */
export async function estimatedStock(productId: string): Promise<{
  value: number;
  confident: boolean;
}> {
  const snapshot = await db.get("stockSnapshot", productId);
  const unsynced = await unsyncedQuantityFor(productId);

  return {
    value: (snapshot?.onHand ?? 0) - unsynced,
    // Confident only when nothing on this device is still queued.
    confident: unsynced === 0,
  };
}

/**
 * Rendered entirely from the local sale object. Nothing here can require a
 * network call — a receipt that needs the server is a receipt that fails at
 * exactly the wrong moment.
 */
export function receiptHtml(sale: LocalSale, shop: ShopInfo): string {
  const money = (cents: number) => `$${(cents / 100).toFixed(2)}`;

  const lines = sale.lines
    .map(
      (l) => `
      <tr>
        <td>${escapeHtml(l.name)}</td>
        <td class="qty">${l.quantity}</td>
        <td class="amt">${money(l.lineTotalCents)}</td>
      </tr>`,
    )
    .join("");

  return `
    <div class="receipt">
      <h1>${escapeHtml(shop.name)}</h1>
      <p class="meta">${new Date(sale.occurredAt).toLocaleString("en-GB")}</p>
      <p class="meta">Ref ${sale.id.slice(0, 8).toUpperCase()}</p>
      <table>${lines}</table>
      <p class="total">${money(sale.totalCents)}</p>
      <p class="meta">${sale.paymentMethod.toUpperCase()}</p>
      ${
        sale.paymentState === "pending_verification"
          ? `<p class="warn">PAYMENT NOT YET VERIFIED</p>`
          : ""
      }
    </div>`;
}

import { serverReachable } from "../net/reachable";
import { db } from "../db/schema";

const BATCH_SIZE = 50;
const BASE_BACKOFF_MS = 2_000;
const MAX_BACKOFF_MS = 5 * 60_000;

let running = false;

export async function scheduleSync(): Promise<void> {
  // Guard against overlapping runs — two workers pushing the same batch would
  // be safe (part 4 makes it idempotent) but it wastes a connection that is
  // already scarce.
  if (running) return;
  running = true;

  try {
    if (!(await serverReachable(API_BASE))) return;

    while (true) {
      const pending = await db.getAll("outbox", undefined, BATCH_SIZE);
      if (pending.length === 0) break;

      const sales = await Promise.all(
        pending.map((entry) => db.get("sales", entry.saleId)),
      );

      const res = await fetch(`${API_BASE}/sync/sales`, {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ sales: sales.filter(Boolean) }),
      });

      if (!res.ok) {
        await backOff(pending);
        break;
      }

      const { accepted }: { accepted: string[] } = await res.json();

      // Clear only what the server explicitly acknowledged. Anything missing
      // stays queued and is retried — never assume success from a 200 alone.
      const tx = db.transaction(["outbox", "sales"], "readwrite");
      for (const id of accepted) {
        await tx.objectStore("outbox").delete(id);
        const sale = await tx.objectStore("sales").get(id);
        if (sale) await tx.objectStore("sales").put({ ...sale, synced: 1 });
      }
      await tx.done;
    }
  } finally {
    running = false;
  }
}

export function nextDelay(attempts: number): number {
  const exponential = BASE_BACKOFF_MS * 2 ** attempts;
  // Jitter stops twenty tills in one shopping centre retrying in lockstep the
  // instant the internet returns, which is its own outage.
  const jitter = Math.random() * 1000;
  return Math.min(exponential + jitter, MAX_BACKOFF_MS);
}