scan2form 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yousuf Omer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# Scan2Form 🖨️ -> 🌐
+
+**Scan documents from a physical scanner directly into your web form.**
+
+Typically, browsers can't access scanners. **Scan2Form** solves this by running a tiny local bridge on your computer.
+
+---
+
+## 🚀 Quick Start for Developers
+
+**1. Install the package**
+```bash
+npm install scan2form
+```
+
+**2. Add to your frontend code**
+```javascript
+import { Scan2Form } from 'scan2form';
+
+const scanner = new Scan2Form();
+
+// Triggers the scan and puts the file into <input type="file" id="my-input" />
+await scanner.scanToInput('my-input');
+```
+
+That's it! The file input is now populated with a PDF, just as if the user uploaded it manually.
+
+---
+
+## 🖥️ Setup for End-Users
+
+To make scanning work, the user needs two things installed on their computer:
+
+### 1. The Scanner Engine
+We rely on a local scanning engine. You can use either **NAPS2** (Recommended for Windows) or **SANE** (Recommended for macOS/Linux).
+
+**Option A: NAPS2 (Windows)**
+*   **[Download NAPS2](https://github.com/cyanfish/naps2/releases#:~:text=naps2%2D8.2.1%2Dwin%2Darm64.exe)** and install it.
+*   **Important:** Ensure `naps2.console` is available in your system PATH.
+*   [How to configure NAPS2 Command Line](https://www.naps2.com/doc/command-line)
+
+    > **Tip (Windows PowerShell):** You can set up an alias to make it simple:
+    > ```powershell
+    > function naps2.console { . "C:\Program Files\NAPS2\NAPS2.Console.exe" $args }
+    > ```
+
+**Option B: SANE (macOS / Linux)**
+*   **macOS:** Install via Homebrew: `brew install sane-backends`
+*   **Linux:** Install via apt: `sudo apt-get install sane-utils`
+*   Verify installation by running `scanimage --version` in your terminal.
+
+### 2. The Bridge Server
+This tiny server listens for commands from your website.
+```bash
+# Run this command in your terminal
+npx scan2form-server
+```
+*   Keep this running while scanning.
+*   It runs locally at `http://127.0.0.1:3000`.
+
+---
+
+## 🛠️ System Requirements
+*   **Node.js**: v16+
+*   **OS**: Windows, Mac, or Linux
+*   **Scanner**: Any scanner supported by your OS drivers.

package/dist/bridge-server.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.app = void 0;
+const express_1 = __importDefault(require("express"));
+const cors_1 = __importDefault(require("cors"));
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const uuid_1 = require("uuid");
+const app = (0, express_1.default)();
+exports.app = app;
+const PORT = 3000; // Localhost only
+// Rule 9.1: Bind only to localhost (enforced in listen)
+// Rule 9.3: Secure temp directory
+const TEMP_DIR = path_1.default.join(__dirname, 'temp_scans');
+if (!fs_1.default.existsSync(TEMP_DIR))
+    fs_1.default.mkdirSync(TEMP_DIR);
+app.use((0, cors_1.default)()); // Allow browser to hit localhost
+app.use(express_1.default.json());
+// Rule 4.2: Health Check
+app.get('/health', (req, res) => {
+    res.json({ status: "ok", engine: "NAPS2-Wrapper", version: "1.0.0" });
+});
+// Serve example for testing
+app.use('/example', express_1.default.static(path_1.default.join(__dirname, '../example')));
+app.use('/dist', express_1.default.static(path_1.default.join(__dirname, '../dist')));
+// --- Scanner Engine Selection ---
+// We check for 'naps2.console' first, then 'scanimage' (SANE).
+function getScannerEngine(callback) {
+    (0, child_process_1.exec)('naps2.console --help', (err) => {
+        if (!err)
+            return callback('naps2');
+        (0, child_process_1.exec)('scanimage --version', (err2) => {
+            if (!err2)
+                return callback('sane');
+            callback(null);
+        });
+    });
+}
+// --- Endpoints ---
+app.get('/devices', (req, res) => {
+    getScannerEngine((engine) => {
+        if (engine === 'naps2') {
+            (0, child_process_1.exec)('naps2.console --list', (error, stdout, stderr) => {
+                if (error) {
+                    console.error("NAPS2 List Error:", stderr);
+                    return res.json([]);
+                }
+                const devices = stdout.split('\n').filter(line => line.trim().length > 0);
+                res.json({ devices });
+            });
+        }
+        else if (engine === 'sane') {
+            (0, child_process_1.exec)('scanimage -L', (error, stdout, stderr) => {
+                if (error) {
+                    console.error("SANE List Error:", stderr);
+                    return res.json([]);
+                }
+                // scanimage -L output: "device `epsonds:libusb:002:003' is a Epson DS-530 II"
+                // We want to return a friendly name or the ID.
+                const devices = stdout.split('\n')
+                    .filter(line => line.includes('is a'))
+                    .map(line => {
+                    // Cleanup string
+                    return line.replace('device `', '').replace(`'`, '');
+                });
+                res.json({ devices });
+            });
+        }
+        else {
+            const msg = "No scanner software found. Please install NAPS2 (Windows) or SANE (Mac/Linux).";
+            console.error(msg);
+            res.json({ devices: [], error: msg });
+        }
+    });
+});
+app.post('/scan', async (req, res) => {
+    const scanId = (0, uuid_1.v4)();
+    const finalPdfPath = path_1.default.join(TEMP_DIR, `scan_${scanId}.pdf`);
+    getScannerEngine((engine) => {
+        if (!engine) {
+            return res.status(500).json({ error: "No scanner software installed (NAPS2 or SANE)." });
+        }
+        if (engine === 'naps2') {
+            const cmd = `naps2.console -o "${finalPdfPath}" -v`;
+            console.log(`Scanning with NAPS2: ${cmd}`);
+            (0, child_process_1.exec)(cmd, (error, stdout, stderr) => {
+                if (error) {
+                    console.error(`NAPS2 Error: ${error.message}`);
+                    return res.status(500).json({ error: "Scan failed", details: stderr });
+                }
+                if (fs_1.default.existsSync(finalPdfPath)) {
+                    res.sendFile(finalPdfPath, () => {
+                        fs_1.default.unlink(finalPdfPath, (err) => { if (err)
+                            console.error("Cleanup error:", err); });
+                    });
+                }
+                else {
+                    res.status(500).json({ error: "Scan completed but PDF not found." });
+                }
+            });
+        }
+        else if (engine === 'sane') {
+            // SANE flow: scanimage -> tiff -> sips -> pdf
+            const tempTiffPath = path_1.default.join(TEMP_DIR, `scan_${scanId}.tiff`);
+            // Default to batch access or single scan. `scanimage --format=tiff > output.tiff`
+            const cmd = `scanimage --format=tiff --mode Color --resolution 300 > "${tempTiffPath}"`;
+            console.log(`Scanning with SANE: ${cmd}`);
+            (0, child_process_1.exec)(cmd, (error, stdout, stderr) => {
+                if (error) {
+                    // scanimage writes progress to stderr, so it might not be a real error unless exit code != 0.
+                    // But exec gives error on non-zero exit.
+                    console.error(`SANE Error: ${error.message}`);
+                    return res.status(500).json({ error: "Scan failed", details: stderr });
+                }
+                // Convert TIFF to PDF using Mac's 'sips' or ImageMagick 'convert'
+                // Since we are targeting Mac fallback, we use 'sips'
+                const convertCmd = `sips -s format pdf "${tempTiffPath}" --out "${finalPdfPath}"`;
+                (0, child_process_1.exec)(convertCmd, (cErr, cOut, cStderr) => {
+                    // Cleanup TIFF immediately
+                    if (fs_1.default.existsSync(tempTiffPath))
+                        fs_1.default.unlinkSync(tempTiffPath);
+                    if (cErr) {
+                        console.error(`Conversion Error: ${cStderr}`);
+                        return res.status(500).json({ error: "Image conversion failed" });
+                    }
+                    if (fs_1.default.existsSync(finalPdfPath)) {
+                        res.sendFile(finalPdfPath, () => {
+                            fs_1.default.unlink(finalPdfPath, (err) => { if (err)
+                                console.error("Cleanup error:", err); });
+                        });
+                    }
+                    else {
+                        res.status(500).json({ error: "Conversion completed but PDF not found." });
+                    }
+                });
+            });
+        }
+    });
+});
+if (require.main === module) {
+    app.listen(PORT, '127.0.0.1', () => {
+        console.log(`Scan2Form Bridge running at http://127.0.0.1:${PORT}`);
+        console.log(`Open Example: http://127.0.0.1:${PORT}/example/index.html`);
+    });
+}

package/dist/esm/scanner-client.js

@@ -0,0 +1,54 @@
+export class Scan2Form {
+    constructor(bridgeUrl = 'http://127.0.0.1:3000') {
+        this.bridgeUrl = bridgeUrl;
+    }
+    // Rule 5.1: Detect Bridge
+    async isAvailable() {
+        try {
+            const res = await fetch(`${this.bridgeUrl}/health`);
+            return res.ok;
+        }
+        catch (e) {
+            return false;
+        }
+    }
+    // List available scanners
+    async getDevices() {
+        try {
+            const res = await fetch(`${this.bridgeUrl}/devices`);
+            if (!res.ok)
+                return { devices: [], error: res.statusText };
+            const data = await res.json();
+            return { devices: data.devices || [], error: data.error };
+        }
+        catch (e) {
+            return { devices: [], error: "Bridge unreachable" };
+        }
+    }
+    // Rule 5.2 & 5.3: Trigger Scan & Receive Blob
+    async scanToInput(inputId) {
+        const inputElement = document.getElementById(inputId);
+        if (!inputElement)
+            throw new Error("Input element not found");
+        try {
+            const response = await fetch(`${this.bridgeUrl}/scan`, { method: 'POST' });
+            if (!response.ok)
+                throw new Error("Scan failed or cancelled at device");
+            const blob = await response.blob();
+            // Rule 5.4: Inject into DataTransfer
+            const file = new File([blob], `scanned_doc_${Date.now()}.pdf`, { type: 'application/pdf' });
+            const dataTransfer = new DataTransfer();
+            dataTransfer.items.add(file);
+            inputElement.files = dataTransfer.files;
+            // Trigger change event so frameworks (React/Vue) detect the update
+            inputElement.dispatchEvent(new Event('change', { bubbles: true }));
+            return { success: true, file: file };
+        }
+        catch (error) {
+            console.error("Scan2Form Error:", error);
+            // Alerting might be annoying in a library, maybe optional? Leaving as is for now but usually libraries shouldn't alert.
+            // alert("Ensure Scan2Form Bridge is running!"); 
+            return { success: false, error: error };
+        }
+    }
+}

package/dist/scanner-client.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Scan2Form = void 0;
+class Scan2Form {
+    constructor(bridgeUrl = 'http://127.0.0.1:3000') {
+        this.bridgeUrl = bridgeUrl;
+    }
+    // Rule 5.1: Detect Bridge
+    async isAvailable() {
+        try {
+            const res = await fetch(`${this.bridgeUrl}/health`);
+            return res.ok;
+        }
+        catch (e) {
+            return false;
+        }
+    }
+    // List available scanners
+    async getDevices() {
+        try {
+            const res = await fetch(`${this.bridgeUrl}/devices`);
+            if (!res.ok)
+                return { devices: [], error: res.statusText };
+            const data = await res.json();
+            return { devices: data.devices || [], error: data.error };
+        }
+        catch (e) {
+            return { devices: [], error: "Bridge unreachable" };
+        }
+    }
+    // Rule 5.2 & 5.3: Trigger Scan & Receive Blob
+    async scanToInput(inputId) {
+        const inputElement = document.getElementById(inputId);
+        if (!inputElement)
+            throw new Error("Input element not found");
+        try {
+            const response = await fetch(`${this.bridgeUrl}/scan`, { method: 'POST' });
+            if (!response.ok)
+                throw new Error("Scan failed or cancelled at device");
+            const blob = await response.blob();
+            // Rule 5.4: Inject into DataTransfer
+            const file = new File([blob], `scanned_doc_${Date.now()}.pdf`, { type: 'application/pdf' });
+            const dataTransfer = new DataTransfer();
+            dataTransfer.items.add(file);
+            inputElement.files = dataTransfer.files;
+            // Trigger change event so frameworks (React/Vue) detect the update
+            inputElement.dispatchEvent(new Event('change', { bubbles: true }));
+            return { success: true, file: file };
+        }
+        catch (error) {
+            console.error("Scan2Form Error:", error);
+            // Alerting might be annoying in a library, maybe optional? Leaving as is for now but usually libraries shouldn't alert.
+            // alert("Ensure Scan2Form Bridge is running!"); 
+            return { success: false, error: error };
+        }
+    }
+}
+exports.Scan2Form = Scan2Form;

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "scan2form",
+  "version": "1.0.0",
+  "description": "Local offline bridge allowing web browsers to access physical scanners (WIA, TWAIN, SANE).",
+  "main": "dist/scanner-client.js",
+  "scripts": {
+    "start": "node dist/bridge-server.js",
+    "example": "npm run build && npm start",
+    "dev": "nodemon src/bridge-server.ts",
+    "build": "tsc && tsc src/scanner-client.ts --target es2020 --module es2020 --moduleResolution node --outDir dist/esm",
+    "test": "jest",
+    "prepublishOnly": "npm run build"
+  },
+  "bin": {
+    "scan2form-server": "dist/bridge-server.js"
+  },
+  "types": "./dist/scanner-client.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "scanner",
+    "twain",
+    "wia",
+    "sane",
+    "web-scanning",
+    "local-bridge"
+  ],
+  "author": "jodeveloper8",
+  "license": "MIT",
+  "dependencies": {
+    "cors": "^2.8.5",
+    "express": "^4.18.2",
+    "uuid": "^9.0.1"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.10.6",
+    "@types/supertest": "^6.0.3",
+    "@types/uuid": "^9.0.7",
+    "jest": "^30.2.0",
+    "nodemon": "^3.0.2",
+    "supertest": "^7.2.2",
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  }
+}