Printer setup in your POS¶

// printing.ts: one place for everything your POS knows about printing.
import { BridgeClient, BridgeError, ReceiptBuilder } from 'pos-hardware-bridge';
import type { PrinterInfo, ReceiptDocument } from 'pos-hardware-bridge';

/** What each kind of print is for. Add your own roles here. */
export type PrintRole = 'receipt' | 'kitchen' | 'invoice';

export interface PrintSettings {
  /** http://127.0.0.1:9191 on the printer computer, the shop address on a tablet. */
  url: string;
  /** Access token (printer computer) or device token (from pairing). */
  token: string;
  /** Printer API name per role. '' = the bridge's default; null = don't print. */
  printers: Record<PrintRole, string | null>;
  /** Print the customer receipt as soon as a sale is saved. */
  autoPrint: boolean;
  copies: number;
}

const STORAGE_KEY = 'pos.printing';

export const DEFAULT_SETTINGS: PrintSettings = {
  url: 'http://127.0.0.1:9191',
  token: '',
  printers: { receipt: '', kitchen: null, invoice: '' },
  autoPrint: true,
  copies: 1,
};

// ---- Saved settings (per device, never in your code or database) ----

export function loadSettings(): PrintSettings {
  try {
    const saved = JSON.parse(localStorage.getItem(STORAGE_KEY) ?? 'null');
    return saved
      ? { ...DEFAULT_SETTINGS, ...saved, printers: { ...DEFAULT_SETTINGS.printers, ...saved.printers } }
      : DEFAULT_SETTINGS;
  } catch {
    return DEFAULT_SETTINGS;
  }
}

export function saveSettings(settings: PrintSettings): void {
  localStorage.setItem(STORAGE_KEY, JSON.stringify(settings));
}

export function isConfigured(settings = loadSettings()): boolean {
  return settings.token !== '';
}

function clientFor(settings: PrintSettings): BridgeClient {
  return new BridgeClient({ url: settings.url, token: settings.token });
}

// ---- Connecting ----

export interface Connection {
  bridgeName: string;
  version: string;
  /** 'local' = this is the printer computer; 'device' = a paired tablet or till. */
  kind: 'local' | 'device';
  printers: PrinterInfo[];
}

/**
 * Check the address and token work, and load the printer list.
 * Throws BridgeError with a message you can show as it is.
 */
export async function testConnection(url: string, token: string): Promise<Connection> {
  const bridge = new BridgeClient({ url, token, timeoutMs: 5000 });
  const health = await bridge.health(); // no token: is it running?
  const me = await bridge.me(); // token: is it accepted?
  const printers = await bridge.printers();
  return {
    bridgeName: health.bridge?.name ?? 'POS Hardware Bridge',
    version: health.bridge?.version ?? '',
    kind: me.kind,
    printers,
  };
}

/** A tablet or till: trade the 6-digit code for this device's own token. */
export async function pairThisDevice(url: string, code: string, deviceName: string) {
  const paired = await BridgeClient.pair({ url, code, name: deviceName });
  return { url: paired.url, token: paired.token };
}

// ---- Printing ----

export type PrintOutcome =
  | { ok: true; printer: string }
  | { ok: false; skipped: true }
  | { ok: false; skipped?: false; message: string; canRetry: boolean };

/**
 * Print to the printer chosen for this role. Never throws: a printer problem
 * must not break a sale. Show `message` and a Reprint button when !ok.
 */
export async function printFor(
  role: PrintRole,
  receipt: ReceiptBuilder | ReceiptDocument,
  options: { title?: string; copies?: number } = {},
): Promise<PrintOutcome> {
  const settings = loadSettings();
  const printer = settings.printers[role];
  if (!isConfigured(settings) || printer === null) return { ok: false, skipped: true };
  try {
    const result = await clientFor(settings).printReceipt(receipt, {
      printer: printer || undefined,
      copies: options.copies ?? settings.copies,
      title: options.title,
    });
    return { ok: true, printer: result.printer };
  } catch (error) {
    if (error instanceof BridgeError) {
      // 0 = no answer: it may or may not have printed, so ask before reprinting.
      return { ok: false, message: error.message, canRetry: error.status !== 0 };
    }
    return { ok: false, message: 'Printing failed.', canRetry: true };
  }
}

/** A4 invoice from HTML, to the printer chosen for 'invoice'. */
export async function printInvoice(html: string, title?: string): Promise<PrintOutcome> {
  const settings = loadSettings();
  const printer = settings.printers.invoice;
  if (!isConfigured(settings) || printer === null) return { ok: false, skipped: true };
  try {
    const result = await clientFor(settings).printDocument({ html }, { printer: printer || undefined, title });
    return { ok: true, printer: result.printer };
  } catch (error) {
    const message = error instanceof BridgeError ? error.message : 'Printing failed.';
    return { ok: false, message, canRetry: !(error instanceof BridgeError && error.status === 0) };
  }
}

export async function printTestPage(role: PrintRole): Promise<PrintOutcome> {
  const settings = loadSettings();
  const printer = settings.printers[role];
  if (printer === null) return { ok: false, skipped: true };
  try {
    const result = await clientFor(settings).printTestPage(printer || undefined);
    return { ok: true, printer: result.printer };
  } catch (error) {
    return { ok: false, message: error instanceof Error ? error.message : 'Printing failed.', canRetry: true };
  }
}

// ---- Live status for the POS header ----

export type PrinterLight = 'ok' | 'warning' | 'error' | 'off';

export interface PrinterStatusSummary {
  light: PrinterLight;
  /** One line for the cashier, e.g. "Front counter: out of paper". */
  text: string;
}

function summarize(status: { printers: Array<{ level: PrinterLight; title: string; name: string }> }): PrinterStatusSummary {
  const worst =
    status.printers.find((p) => p.level === 'error') ??
    status.printers.find((p) => p.level === 'warning') ??
    status.printers.find((p) => p.level === 'off');
  if (status.printers.length === 0) return { light: 'warning', text: 'No printers set up in the bridge' };
  return worst ? { light: worst.level, text: `${worst.name}: ${worst.title}` } : { light: 'ok', text: 'Printers ready' };
}

/**
 * Calls `onChange` now and whenever a printer's status changes. Also checks
 * every 10 s, so it recovers when the bridge restarts. Returns a function
 * that stops watching.
 */
export function watchPrinterStatus(onChange: (summary: PrinterStatusSummary) => void): () => void {
  const settings = loadSettings();
  if (!isConfigured(settings)) {
    onChange({ light: 'off', text: 'Printing not set up' });
    return () => {};
  }
  const bridge = clientFor(settings);
  let stopped = false;
  let stopListening = () => {};
  let retry: ReturnType<typeof setTimeout> | undefined;

  const connect = async () => {
    try {
      onChange(summarize(await bridge.status()));
      stopListening = bridge.onStatus((payload) => onChange(summarize(payload as any)));
    } catch (error) {
      onChange({ light: 'error', text: error instanceof BridgeError ? error.message : 'Bridge not reachable' });
    }
  };
  // Poll every 10 s as a safety net: covers a dropped socket or a bridge restart.
  const poll = async () => {
    if (stopped) return;
    try {
      onChange(summarize(await bridge.status()));
    } catch (error) {
      onChange({ light: 'error', text: error instanceof BridgeError ? error.message : 'Bridge not reachable' });
    }
    retry = setTimeout(poll, 10_000);
  };

  void connect().then(() => (retry = setTimeout(poll, 10_000)));
  return () => {
    stopped = true;
    clearTimeout(retry);
    stopListening();
  };
}

// PrinterSettings.tsx: the "Printers" page in your POS settings.
import { useEffect, useState } from 'react';
import type { PrinterInfo } from 'pos-hardware-bridge';
import {
  type Connection,
  type PrintRole,
  type PrintSettings,
  loadSettings,
  pairThisDevice,
  printTestPage,
  saveSettings,
  testConnection,
} from './printing';

const ROLES: Array<{ role: PrintRole; label: string; kind: PrinterInfo['kind'] }> = [
  { role: 'receipt', label: 'Customer receipts', kind: 'receipt' },
  { role: 'kitchen', label: 'Kitchen tickets', kind: 'receipt' },
  { role: 'invoice', label: 'A4 invoices', kind: 'document' },
];

export function PrinterSettings() {
  const [settings, setSettings] = useState<PrintSettings>(loadSettings);
  const [connection, setConnection] = useState<Connection | null>(null);
  const [message, setMessage] = useState('');
  const [busy, setBusy] = useState(false);
  const [mode, setMode] = useState<'this-computer' | 'pair'>(
    settings.url.includes('127.0.0.1') || settings.url.includes('localhost') ? 'this-computer' : 'pair',
  );
  const [code, setCode] = useState('');
  const [deviceName, setDeviceName] = useState('');

  const update = (next: PrintSettings) => {
    setSettings(next);
    saveSettings(next);
  };

  const connect = async (url: string, token: string) => {
    setBusy(true);
    setMessage('');
    try {
      const result = await testConnection(url, token);
      setConnection(result);
      update({ ...settings, url, token });
      setMessage(`Connected to ${result.bridgeName}.`);
    } catch (error) {
      setConnection(null);
      setMessage(error instanceof Error ? error.message : String(error));
    } finally {
      setBusy(false);
    }
  };

  const pair = async () => {
    setBusy(true);
    setMessage('');
    try {
      const { url, token } = await pairThisDevice(settings.url, code, deviceName || 'POS device');
      setCode('');
      await connect(url, token);
    } catch (error) {
      setMessage(error instanceof Error ? error.message : String(error));
      setBusy(false);
    }
  };

  // Already set up: load the printer list when the page opens.
  useEffect(() => {
    if (settings.token) void connect(settings.url, settings.token);
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, []);

  return (
    <section>
      <h2>Printers</h2>

      {/* Step 1: connect */}
      <fieldset disabled={busy}>
        <legend>1. Connect to POS Hardware Bridge</legend>
        <label>
          <input type="radio" checked={mode === 'this-computer'} onChange={() => setMode('this-computer')} />
          Printers are connected to this computer
        </label>
        <label>
          <input
            type="radio"
            checked={mode === 'pair'}
            onChange={() => {
              setMode('pair');
              setSettings({ ...settings, url: '' }); // the shop address, typed below
            }}
          />
          Printers are connected to another computer in the shop
        </label>

        {mode === 'this-computer' ? (
          <>
            <p>In the bridge, open <b>Connect your POS</b> and copy the access token.</p>
            <input
              type="password"
              placeholder="Access token"
              value={settings.token}
              onChange={(e) => setSettings({ ...settings, url: 'http://127.0.0.1:9191', token: e.target.value.trim() })}
            />
            <button onClick={() => connect('http://127.0.0.1:9191', settings.token)}>Connect</button>
          </>
        ) : (
          <>
            <p>
              On the printer computer, open <b>Connect your POS → Phones &amp; tablets</b>, turn on network
              access and click <b>Get a code</b>.
            </p>
            <input
              placeholder="Bridge address, e.g. http://192.168.1.20:9191"
              value={settings.url}
              onChange={(e) => setSettings({ ...settings, url: e.target.value.trim() })}
            />
            <input placeholder="6-digit code" inputMode="numeric" value={code} onChange={(e) => setCode(e.target.value)} />
            <input placeholder="Name for this device, e.g. Till 2" value={deviceName} onChange={(e) => setDeviceName(e.target.value)} />
            <button onClick={pair} disabled={!code}>Pair</button>
          </>
        )}
        {message && <p role="status">{message}</p>}
      </fieldset>

      {/* Step 2: choose printers */}
      {connection && (
        <fieldset>
          <legend>2. Choose printers</legend>
          {ROLES.map(({ role, label, kind }) => (
            <div key={role}>
              <label>
                {label}{' '}
                <select
                  value={settings.printers[role] ?? 'none'}
                  onChange={(e) =>
                    update({
                      ...settings,
                      printers: { ...settings.printers, [role]: e.target.value === 'none' ? null : e.target.value },
                    })
                  }
                >
                  <option value="">Default printer</option>
                  {connection.printers
                    .filter((p) => p.kind === kind)
                    .map((p) => (
                      <option key={p.id} value={p.id}>
                        {p.name} {p.ready ? '' : '(not ready)'}
                      </option>
                    ))}
                  <option value="none">Don't print</option>
                </select>
              </label>
              <button
                disabled={settings.printers[role] === null}
                onClick={async () => {
                  const result = await printTestPage(role);
                  setMessage(result.ok ? `Test page sent to ${result.printer}.` : 'message' in result ? result.message : '');
                }}
              >
                Test print
              </button>
            </div>
          ))}
          {connection.printers.length === 0 && <p>No printers yet: add one in the bridge, then reopen this page.</p>}
        </fieldset>
      )}

      {/* Step 3: options */}
      {connection && (
        <fieldset>
          <legend>3. Options</legend>
          <label>
            <input
              type="checkbox"
              checked={settings.autoPrint}
              onChange={(e) => update({ ...settings, autoPrint: e.target.checked })}
            />
            Print the receipt automatically after each sale
          </label>
          <label>
            Copies{' '}
            <input
              type="number"
              min={1}
              max={5}
              value={settings.copies}
              onChange={(e) => update({ ...settings, copies: Math.min(5, Math.max(1, Number(e.target.value) || 1)) })}
            />
          </label>
        </fieldset>
      )}
    </section>
  );
}