checkscanner 0.1.2__tar.gz

checkscanner-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DiscipleMakers
+
+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.

checkscanner-0.1.2/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md LICENSE
+graft src/checkscanner/static
+graft src/checkscanner/swagger
+recursive-include src/checkscanner/data *.ttf *.json *.sql
+global-exclude *.py[cod] __pycache__ .gitkeep

checkscanner-0.1.2/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: checkscanner
+Version: 0.1.2
+Summary: Check scanner API server and admin console
+Home-page: https://bitbucket.org/disciplemakers/check-reader
+Author: DiscipleMakers
+License: MIT
+Keywords: check scanner,micr,magtek,rdm
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: Bottle
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: <3.13,>=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gevent<22.0.0,>=1.5.0; python_version < "3.7"
+Requires-Dist: gevent>=23.0.0; python_version >= "3.7"
+Requires-Dist: Pillow<9.0.0,>=5.0.0; python_version < "3.7"
+Requires-Dist: Pillow>=10.0.0; python_version >= "3.7"
+Requires-Dist: pyftpdlib<2.0.0,>=1.5.0; python_version < "3.7"
+Requires-Dist: pyftpdlib>=1.5.7; python_version >= "3.7"
+Requires-Dist: PyJWT<2.5.0,>=2.0.0; python_version < "3.7"
+Requires-Dist: PyJWT>=2.8.0; python_version >= "3.7"
+Requires-Dist: requests<2.28.0,>=2.20.0; python_version < "3.7"
+Requires-Dist: requests>=2.31.0; python_version >= "3.7"
+Requires-Dist: toml>=0.10.0
+Requires-Dist: click<8.1,>=7.1; python_version < "3.7"
+Requires-Dist: click>=8.1; python_version >= "3.7"
+Requires-Dist: rich<13.0,>=12.0; python_version < "3.7"
+Requires-Dist: rich>=13.0; python_version >= "3.7"
+Requires-Dist: questionary<2.0,>=1.10.0; python_version < "3.8"
+Requires-Dist: questionary>=2.0; python_version >= "3.8"
+Dynamic: license-file
+
+# checkscanner
+
+Python package for the check scanner backend. Manages connections to Magtek and RDM check scanning devices, extracts MICR data and check images, and serves them through a JWT-authenticated REST API.
+
+## Requirements
+
+- Python 3.6+
+- SQLite3
+- pip 21.3.1+ (required on Python 3.6 to resolve pre-built wheels)
+
+## Installation
+
+Ensure pip is up to date before installing:
+
+```bash
+pip install --upgrade pip
+```
+
+Then install the package from PyPI:
+
+```bash
+pip install checkscanner
+```
+
+Or from the source tree:
+
+```bash
+cd server
+pip install .
+```
+
+For development (changes take effect without reinstalling):
+
+```bash
+pip install -e .
+```
+
+## Building the Frontend
+
+The frontend must be built and bundled into the package before installing. Run this once from the source tree (requires Node.js):
+
+```bash
+checkscanner build
+pip install .   # reinstall to pick up the bundled frontend
+```
+
+In development with an editable install, `checkscanner build` copies the output directly into `src/checkscanner/static/` so it takes effect immediately without reinstalling.
+
+## Usage
+
+The package installs two commands. Run them from your project directory — config files and the database are created there.
+
+```bash
+# Start the API server (serves UI at http://localhost:8000/).
+# Runs first-time setup automatically if needed.
+checkscanner
+
+# Open the interactive admin console
+checkscanner-cli
+```
+
+`checkscanner` also accepts subcommands (run `checkscanner --help` or `checkscanner <command> --help` for details):
+
+```bash
+checkscanner server [options]   # Same as no arguments; see `checkscanner server --help`
+checkscanner setup [-i]         # Create anything missing: config/, server.db, admin user (-i: edit config first)
+checkscanner status             # Show config, database and connection status
+checkscanner admin              # Same as checkscanner-cli
+checkscanner build              # Build the frontend and bundle it into the package (source tree only)
+
+checkscanner user list|add|passwd|delete
+checkscanner profile list|add|delete
+checkscanner config show|edit|rotate-keys
+checkscanner token <username>[:<password>]   # or -u <username> [-p <password>]
+```
+
+Server options can also be passed directly, e.g. `checkscanner --port 9000`.
+
+## First-Time Setup
+
+`checkscanner setup` (also runs automatically before the server and admin console start) creates:
+
+| File | Description |
+|---|---|
+| `config/config.toml` | Server host, port, debug mode |
+| `config/auth.toml` | JWT signing key, FTP credentials |
+| `server.db` | SQLite database |
+| `admin_credentials.txt` | Generated admin username and password — delete after noting |
+
+## Admin Console
+
+`checkscanner-cli` opens an arrow-key menu for managing the server:
+
+- View server status
+- List, add and delete users; reset passwords
+- List, add and delete check scanner profiles
+- Edit config and regenerate auth keys
+- Get a bearer token for API testing
+- Start the server, optionally restarting it automatically when it stops
+
+Every menu action is also available as a `checkscanner` subcommand for scripting.
+
+## API
+
+Swagger UI is available at `http://localhost:8000/docs` when the server is running.
+
+| Method | Endpoint | Description |
+|---|---|---|
+| POST | `/token` | Authenticate, receive JWT |
+| GET/POST | `/connections` | List or create reader connections |
+| DELETE | `/connections/<id>` | Disconnect from reader |
+| GET/PUT | `/connections/<id>/check` | Get check data or return check to queue |
+| GET/POST/PATCH/DELETE | `/profiles` | Manage reader device profiles |
+| GET/POST/PATCH/DELETE | `/users` | Manage users (admin only) |
+
+## Supported Devices
+
+| Type | Protocol |
+|---|---|
+| Magtek | Telnet + FTP |
+| RDM | HTTPS (XML) |
+
+## Project Structure
+
+```
+src/
+└── checkscanner/
+    ├── app.py                    # Bottle API server
+    ├── admin_console.py          # Interactive admin CLI
+    ├── active_scanners.py        # In-memory scanner connection registry
+    ├── auth.py                   # Password hashing and JWT verification
+    ├── ftp_server.py             # FTP server for Magtek image uploads
+    ├── debugger.py               # Colored terminal logging
+    ├── bottle/                   # Vendored Bottle framework + plugins
+    ├── resources/                # REST resource handlers
+    ├── check_scanner_handlers/   # Device-specific connection handlers
+    ├── static/                   # Bundled frontend (populated by `checkscanner build`)
+    ├── swagger/                  # Bundled Swagger UI
+    └── data/                     # Bundled assets (schema, font, API spec)
+```
+
+## Releasing to PyPI
+
+Releases are published by the Bitbucket pipeline (`bitbucket-pipelines.yml`) when a `v*` tag is pushed. The pipeline builds the frontend, bundles it into the package, builds the sdist and wheel, uploads them to PyPI, and uploads the wheel to Bitbucket Downloads.
+
+1. Bump `version` in `setup.cfg` (PyPI rejects re-uploads of an existing version).
+2. Commit, then tag with the matching version and push the tag:
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+
+The pipeline fails if the tag does not match `setup.cfg`. It needs these secured repository variables:
+
+| Variable | Purpose |
+|---|---|
+| `PYPI_TOKEN` | PyPI API token (`pypi-...`) used by twine |
+| `BB_TOKEN` | Bitbucket token for the Downloads upload |
+
+To build locally instead:
+
+```bash
+checkscanner build          # bundle the frontend first
+python -m build             # creates dist/*.tar.gz and dist/*.whl
+twine check dist/*
+twine upload dist/*
+```
+
+## Dependencies
+
+| Package | Purpose |
+|---|---|
+| `gevent` | Async concurrency for the server |
+| `Pillow` | Check image processing |
+| `pyftpdlib` | FTP server for Magtek readers |
+| `PyJWT` | JWT signing and verification |
+| `requests` | HTTP client for RDM readers |
+| `toml` | Config file parsing |

checkscanner-0.1.2/README.md

@@ -0,0 +1,178 @@
+# checkscanner
+
+Python package for the check scanner backend. Manages connections to Magtek and RDM check scanning devices, extracts MICR data and check images, and serves them through a JWT-authenticated REST API.
+
+## Requirements
+
+- Python 3.6+
+- SQLite3
+- pip 21.3.1+ (required on Python 3.6 to resolve pre-built wheels)
+
+## Installation
+
+Ensure pip is up to date before installing:
+
+```bash
+pip install --upgrade pip
+```
+
+Then install the package from PyPI:
+
+```bash
+pip install checkscanner
+```
+
+Or from the source tree:
+
+```bash
+cd server
+pip install .
+```
+
+For development (changes take effect without reinstalling):
+
+```bash
+pip install -e .
+```
+
+## Building the Frontend
+
+The frontend must be built and bundled into the package before installing. Run this once from the source tree (requires Node.js):
+
+```bash
+checkscanner build
+pip install .   # reinstall to pick up the bundled frontend
+```
+
+In development with an editable install, `checkscanner build` copies the output directly into `src/checkscanner/static/` so it takes effect immediately without reinstalling.
+
+## Usage
+
+The package installs two commands. Run them from your project directory — config files and the database are created there.
+
+```bash
+# Start the API server (serves UI at http://localhost:8000/).
+# Runs first-time setup automatically if needed.
+checkscanner
+
+# Open the interactive admin console
+checkscanner-cli
+```
+
+`checkscanner` also accepts subcommands (run `checkscanner --help` or `checkscanner <command> --help` for details):
+
+```bash
+checkscanner server [options]   # Same as no arguments; see `checkscanner server --help`
+checkscanner setup [-i]         # Create anything missing: config/, server.db, admin user (-i: edit config first)
+checkscanner status             # Show config, database and connection status
+checkscanner admin              # Same as checkscanner-cli
+checkscanner build              # Build the frontend and bundle it into the package (source tree only)
+
+checkscanner user list|add|passwd|delete
+checkscanner profile list|add|delete
+checkscanner config show|edit|rotate-keys
+checkscanner token <username>[:<password>]   # or -u <username> [-p <password>]
+```
+
+Server options can also be passed directly, e.g. `checkscanner --port 9000`.
+
+## First-Time Setup
+
+`checkscanner setup` (also runs automatically before the server and admin console start) creates:
+
+| File | Description |
+|---|---|
+| `config/config.toml` | Server host, port, debug mode |
+| `config/auth.toml` | JWT signing key, FTP credentials |
+| `server.db` | SQLite database |
+| `admin_credentials.txt` | Generated admin username and password — delete after noting |
+
+## Admin Console
+
+`checkscanner-cli` opens an arrow-key menu for managing the server:
+
+- View server status
+- List, add and delete users; reset passwords
+- List, add and delete check scanner profiles
+- Edit config and regenerate auth keys
+- Get a bearer token for API testing
+- Start the server, optionally restarting it automatically when it stops
+
+Every menu action is also available as a `checkscanner` subcommand for scripting.
+
+## API
+
+Swagger UI is available at `http://localhost:8000/docs` when the server is running.
+
+| Method | Endpoint | Description |
+|---|---|---|
+| POST | `/token` | Authenticate, receive JWT |
+| GET/POST | `/connections` | List or create reader connections |
+| DELETE | `/connections/<id>` | Disconnect from reader |
+| GET/PUT | `/connections/<id>/check` | Get check data or return check to queue |
+| GET/POST/PATCH/DELETE | `/profiles` | Manage reader device profiles |
+| GET/POST/PATCH/DELETE | `/users` | Manage users (admin only) |
+
+## Supported Devices
+
+| Type | Protocol |
+|---|---|
+| Magtek | Telnet + FTP |
+| RDM | HTTPS (XML) |
+
+## Project Structure
+
+```
+src/
+└── checkscanner/
+    ├── app.py                    # Bottle API server
+    ├── admin_console.py          # Interactive admin CLI
+    ├── active_scanners.py        # In-memory scanner connection registry
+    ├── auth.py                   # Password hashing and JWT verification
+    ├── ftp_server.py             # FTP server for Magtek image uploads
+    ├── debugger.py               # Colored terminal logging
+    ├── bottle/                   # Vendored Bottle framework + plugins
+    ├── resources/                # REST resource handlers
+    ├── check_scanner_handlers/   # Device-specific connection handlers
+    ├── static/                   # Bundled frontend (populated by `checkscanner build`)
+    ├── swagger/                  # Bundled Swagger UI
+    └── data/                     # Bundled assets (schema, font, API spec)
+```
+
+## Releasing to PyPI
+
+Releases are published by the Bitbucket pipeline (`bitbucket-pipelines.yml`) when a `v*` tag is pushed. The pipeline builds the frontend, bundles it into the package, builds the sdist and wheel, uploads them to PyPI, and uploads the wheel to Bitbucket Downloads.
+
+1. Bump `version` in `setup.cfg` (PyPI rejects re-uploads of an existing version).
+2. Commit, then tag with the matching version and push the tag:
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+
+The pipeline fails if the tag does not match `setup.cfg`. It needs these secured repository variables:
+
+| Variable | Purpose |
+|---|---|
+| `PYPI_TOKEN` | PyPI API token (`pypi-...`) used by twine |
+| `BB_TOKEN` | Bitbucket token for the Downloads upload |
+
+To build locally instead:
+
+```bash
+checkscanner build          # bundle the frontend first
+python -m build             # creates dist/*.tar.gz and dist/*.whl
+twine check dist/*
+twine upload dist/*
+```
+
+## Dependencies
+
+| Package | Purpose |
+|---|---|
+| `gevent` | Async concurrency for the server |
+| `Pillow` | Check image processing |
+| `pyftpdlib` | FTP server for Magtek readers |
+| `PyJWT` | JWT signing and verification |
+| `requests` | HTTP client for RDM readers |
+| `toml` | Config file parsing |

checkscanner-0.1.2/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=42"]
+build-backend = "setuptools.build_meta"

checkscanner-0.1.2/setup.cfg

@@ -0,0 +1,54 @@
+[metadata]
+name = checkscanner
+version = 0.1.2
+description = Check scanner API server and admin console
+long_description = file: README.md
+long_description_content_type = text/markdown
+author = DiscipleMakers
+url = https://bitbucket.org/disciplemakers/check-reader
+license = MIT
+license_files = LICENSE
+keywords = check scanner, micr, magtek, rdm
+classifiers = 
+	Programming Language :: Python :: 3
+	Operating System :: OS Independent
+	Framework :: Bottle
+	Topic :: Office/Business :: Financial
+
+[options]
+package_dir = 
+	= src
+packages = find_namespace:
+python_requires = >=3.6, <3.13
+include_package_data = True
+install_requires = 
+	gevent>=1.5.0,<22.0.0; python_version < "3.7"
+	gevent>=23.0.0; python_version >= "3.7"
+	Pillow>=5.0.0,<9.0.0; python_version < "3.7"
+	Pillow>=10.0.0; python_version >= "3.7"
+	pyftpdlib>=1.5.0,<2.0.0; python_version < "3.7"
+	pyftpdlib>=1.5.7; python_version >= "3.7"
+	PyJWT>=2.0.0,<2.5.0; python_version < "3.7"
+	PyJWT>=2.8.0; python_version >= "3.7"
+	requests>=2.20.0,<2.28.0; python_version < "3.7"
+	requests>=2.31.0; python_version >= "3.7"
+	toml>=0.10.0
+	click>=7.1,<8.1; python_version < "3.7"
+	click>=8.1; python_version >= "3.7"
+	rich>=12.0,<13.0; python_version < "3.7"
+	rich>=13.0; python_version >= "3.7"
+	questionary>=1.10.0,<2.0; python_version < "3.8"
+	questionary>=2.0; python_version >= "3.8"
+
+[options.packages.find]
+where = src
+
+[options.entry_points]
+console_scripts = 
+	checkscanner = checkscanner.cli:main
+	checkscanner-cli = checkscanner.cli:admin_main
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

checkscanner-0.1.2/setup.py

@@ -0,0 +1,2 @@
+from setuptools import setup
+setup()

checkscanner-0.1.2/src/checkscanner/__init__.py

@@ -0,0 +1,5 @@
+import os
+
+DATA_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "data")
+STATIC_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "static")
+SWAGGER_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "swagger")

checkscanner-0.1.2/src/checkscanner/active_scanners.py

@@ -0,0 +1,53 @@
+from threading import Thread
+from . import debugger
+from .check_scanner_handlers import MagtekScannerHandler, RDMScannerHandler, CheckScannerHandler
+from .ftp_server import DummyFTP
+
+class Singleton (type):
+    _instances = {}
+    def __call__(cls, *args, **kwargs):
+        if cls not in cls._instances:
+            cls._instances[cls] = super(Singleton, cls).__call__(*args, **kwargs)
+        return cls._instances[cls]
+
+class ActiveScanners(dict, metaclass=Singleton):
+
+    handlers = {
+        "magtek": MagtekScannerHandler,
+        "rdm": RDMScannerHandler
+    }
+
+    def __init__(self, sleep_time = 5, handlers: dict = None) -> None:
+        debugger.print("Initializing active scanners handler")
+        self.sleep_time = sleep_time
+        self.ftp = None
+        if handlers:
+            self.handlers = handlers
+        self.started = False
+
+    def newReaderHandler(self, reader_type) -> CheckScannerHandler:
+        handler = self.handlers[reader_type](self)
+        if reader_type == "magtek":
+            if not self.ftp:
+                self.ftp = DummyFTP()
+                self.ftp_thread = Thread(target=self.ftp.start, daemon=True).start()
+            handler.ftp = self.ftp
+        return handler
+
+    def isReaderActive(self, reader_host):
+        for crh in self.values():
+            if reader_host == crh.host:
+                return True
+        return False
+
+    def jsonSerialize(self):
+        return {
+            "active_scanners": [{"conn_id": conn_id, **conn} for conn_id, conn in self.items()]
+        }
+
+    def start(self):
+        if not self.started:
+            self.started = True
+
+    def stop(self):
+        self.started = False