build: generate desktop application release artifacts and update project configuration

apps/web/src/hooks/use-electron-printer.ts

@@ -0,0 +1,109 @@
+import { useState, useCallback } from 'react';
+
+// ─── Types ──────────────────────────────────────────────────────
+
+export interface UseElectronPrinterReturn {
+  /** List of available printers (populated after calling `refreshPrinters`) */
+  printers: ElectronPrinterInfo[];
+  /** Whether a printer operation is in progress */
+  loading: boolean;
+  /** Last error message, if any */
+  error: string | null;
+  /** Whether the app is running inside Electron */
+  isElectron: boolean;
+  /** Fetch the current list of available printers */
+  refreshPrinters: () => Promise<ElectronPrinterInfo[]>;
+  /** Print with the given options. Returns success/failure. */
+  print: (options?: ElectronPrintOptions) => Promise<ElectronPrintResult>;
+}
+
+/**
+ * React hook for Electron printer integration.
+ *
+ * Provides methods to list available printers and trigger print jobs
+ * via the secure `window.electronAPI` bridge.
+ *
+ * Safe to use in both Electron and browser environments.
+ *
+ * @example
+ * ```tsx
+ * function PrintButton() {
+ *   const { printers, refreshPrinters, print, loading } = useElectronPrinter();
+ *
+ *   useEffect(() => { refreshPrinters(); }, []);
+ *
+ *   const handlePrint = async () => {
+ *     const result = await print({ silent: true, deviceName: printers[0]?.name });
+ *     if (!result.success) alert(`Print failed: ${result.failureReason}`);
+ *   };
+ *
+ *   return (
+ *     <button onClick={handlePrint} disabled={loading || printers.length === 0}>
+ *       Print
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export function useElectronPrinter(): UseElectronPrinterReturn {
+  const [printers, setPrinters] = useState<ElectronPrinterInfo[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const isElectron = typeof window !== 'undefined' && !!window.electronAPI;
+
+  const refreshPrinters = useCallback(async (): Promise<ElectronPrinterInfo[]> => {
+    if (!window.electronAPI) {
+      setError('Not running in Electron');
+      return [];
+    }
+
+    setLoading(true);
+    setError(null);
+    try {
+      const result = await window.electronAPI.getPrinters();
+      setPrinters(result);
+      return result;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Failed to get printers';
+      setError(message);
+      return [];
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  const print = useCallback(
+    async (options?: ElectronPrintOptions): Promise<ElectronPrintResult> => {
+      if (!window.electronAPI) {
+        return { success: false, failureReason: 'Not running in Electron' };
+      }
+
+      setLoading(true);
+      setError(null);
+      try {
+        const result = await window.electronAPI.print(options);
+        if (!result.success && result.failureReason) {
+          setError(result.failureReason);
+        }
+        return result;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : 'Print failed';
+        setError(message);
+        return { success: false, failureReason: message };
+      } finally {
+        setLoading(false);
+      }
+    },
+    [],
+  );
+
+  return {
+    printers,
+    loading,
+    error,
+    isElectron,
+    refreshPrinters,
+    print,
+  };
+}

apps/web/src/hooks/use-electron-updater.ts

@@ -0,0 +1,139 @@
+import { useState, useEffect, useCallback } from 'react';
+
+// ─── Types ──────────────────────────────────────────────────────
+
+export type UpdateStatus =
+  | 'idle'
+  | 'checking'
+  | 'available'
+  | 'not-available'
+  | 'downloading'
+  | 'ready'
+  | 'error';
+
+export interface UseElectronUpdaterReturn {
+  /** Current status of the auto-updater lifecycle */
+  status: UpdateStatus;
+  /** Download progress percentage (0–100) */
+  progress: number;
+  /** Download speed in bytes per second */
+  bytesPerSecond: number;
+  /** Information about the available/downloaded update */
+  updateInfo: ElectronUpdateInfo | null;
+  /** Error message if the updater encountered an issue */
+  errorMessage: string | null;
+  /** Whether the app is running inside Electron */
+  isElectron: boolean;
+  /** Trigger a manual update check */
+  checkForUpdates: () => void;
+  /** Quit the app and install the downloaded update */
+  installUpdate: () => void;
+}
+
+/**
+ * React hook for the Electron auto-updater.
+ *
+ * Subscribes to all update lifecycle events via `window.electronAPI`
+ * and provides reactive state for building an update notification UI.
+ *
+ * Safe to use in both Electron and browser environments — all
+ * Electron-specific calls are gated behind `window.electronAPI` checks.
+ *
+ * @example
+ * ```tsx
+ * function UpdateBanner() {
+ *   const { status, progress, updateInfo, checkForUpdates, installUpdate } = useElectronUpdater();
+ *
+ *   if (status === 'available') {
+ *     return <div>Update {updateInfo?.version} available! Downloading...</div>;
+ *   }
+ *   if (status === 'downloading') {
+ *     return <div>Downloading... {progress.toFixed(0)}%</div>;
+ *   }
+ *   if (status === 'ready') {
+ *     return <button onClick={installUpdate}>Restart to update</button>;
+ *   }
+ *   return <button onClick={checkForUpdates}>Check for updates</button>;
+ * }
+ * ```
+ */
+export function useElectronUpdater(): UseElectronUpdaterReturn {
+  const [status, setStatus] = useState<UpdateStatus>('idle');
+  const [progress, setProgress] = useState(0);
+  const [bytesPerSecond, setBytesPerSecond] = useState(0);
+  const [updateInfo, setUpdateInfo] = useState<ElectronUpdateInfo | null>(null);
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+
+  const isElectron = typeof window !== 'undefined' && !!window.electronAPI;
+
+  useEffect(() => {
+    if (!window.electronAPI) return;
+
+    const api = window.electronAPI;
+
+    const unsubChecking = api.onUpdateChecking(() => {
+      setStatus('checking');
+      setErrorMessage(null);
+    });
+
+    const unsubAvailable = api.onUpdateAvailable((info) => {
+      setStatus('available');
+      setUpdateInfo(info);
+    });
+
+    const unsubNotAvailable = api.onUpdateNotAvailable((info) => {
+      setStatus('not-available');
+      setUpdateInfo(info);
+    });
+
+    const unsubProgress = api.onDownloadProgress((progressInfo) => {
+      setStatus('downloading');
+      setProgress(progressInfo.percent);
+      setBytesPerSecond(progressInfo.bytesPerSecond);
+    });
+
+    const unsubDownloaded = api.onUpdateDownloaded((info) => {
+      setStatus('ready');
+      setProgress(100);
+      setUpdateInfo(info);
+    });
+
+    const unsubError = api.onUpdateError((error) => {
+      setStatus('error');
+      setErrorMessage(error);
+    });
+
+    // Cleanup all listeners on unmount
+    return () => {
+      unsubChecking();
+      unsubAvailable();
+      unsubNotAvailable();
+      unsubProgress();
+      unsubDownloaded();
+      unsubError();
+    };
+  }, []);
+
+  const checkForUpdates = useCallback(() => {
+    if (!window.electronAPI) return;
+    setStatus('checking');
+    setErrorMessage(null);
+    window.electronAPI.checkForUpdates();
+  }, []);
+
+  const installUpdate = useCallback(() => {
+    if (!window.electronAPI) return;
+    window.electronAPI.installUpdate();
+  }, []);
+
+  return {
+    status,
+    progress,
+    bytesPerSecond,
+    updateInfo,
+    errorMessage,
+    isElectron,
+    checkForUpdates,
+    installUpdate,
+  };
+}