Metadata-Version: 2.4
Name: checkscanner
Version: 0.1.8
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,>=9.5.0; python_version == "3.7"
Requires-Dist: Pillow>=10.3.0; python_version >= "3.8"
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"
Provides-Extra: test
Requires-Dist: pytest<7.1,>=6.2; python_version < "3.7" and extra == "test"
Requires-Dist: pytest>=7.0; python_version >= "3.7" and extra == "test"
Dynamic: license-file

# checkscanner

Check scanner server for Magtek and RDM check readers. It connects to the devices, extracts MICR data and check images, and serves them through a web interface and a JWT-authenticated REST API.

## Requirements

- Python 3.6+
- pip 21.3.1+ (required on Python 3.6 to resolve pre-built wheels)
- [GNU screen](https://www.gnu.org/software/screen/) (optional, for `checkscanner screen`)

## Installation

Update pip, then install the package:

```bash
pip install --upgrade pip
pip install checkscanner
```

To upgrade an existing install:

```bash
pip install --upgrade checkscanner
```

## Setup

Pick a directory to run the server from. Config files and the database are created there, so always run `checkscanner` from the same directory.

```bash
mkdir checkscanner && cd checkscanner
checkscanner setup        # add -i to edit the config interactively first
```

Setup creates anything that is missing:

| File | Description |
|---|---|
| `config/config.toml` | Server host, port, debug mode, optional log file |
| `config/auth.toml` | JWT signing key; optional FTP credentials for Magtek readers |
| `server.db` | SQLite database |
| `admin_credentials.txt` | Generated admin username and password — delete after noting |

Setup also runs automatically before the server and admin console start.

## Usage

Start the server, then open the web interface at `http://localhost:8000/`:

```bash
checkscanner
```

Server options can be passed directly, e.g. `checkscanner --port 9000`. Run `checkscanner server --help` for the full list.

Warnings and errors go to the console. Add `--debug` (or `debug = true` in `config.toml`) to see everything. Setup turns on a log file at `logs/checkscanner.log`, which gets info and above (everything with debug). Change or remove `log_file` in `config.toml`, or pass `--log-file`; the file rotates at 5 MB and keeps 5 old copies. To read the log file from the web interface, set `ui_logs = true` in `config.toml` or turn on "Allow viewing logs in the web UI" on the Settings page (off by default); admins then get a Logs page.

Magtek readers upload check images over FTP. The FTP server only starts when a Magtek reader connects, and its settings are optional: without `ftp_user`/`ftp_pass` in `auth.toml` it uses `check-reader` and a random password, which is sent to the reader on connect.

Open the interactive admin console:

```bash
checkscanner-cli
```

The admin console is an arrow-key menu for viewing server status, managing users and scanner profiles, editing config, regenerating auth keys, getting a bearer token, and starting the server (optionally restarting it when it stops).

### Commands

Every admin console action is also available as a `checkscanner` subcommand. Run `checkscanner --help` or `checkscanner <command> --help` for details.

```bash
checkscanner server [options]   # Start the server (same as no arguments)
checkscanner setup [-i]         # Create missing config/, server.db and admin user (-i: edit config first)
checkscanner status             # Show config, database and connection status
checkscanner admin              # Open the admin console (same as checkscanner-cli)

checkscanner user list|add|passwd|delete
checkscanner profile list|add|delete
checkscanner config show|edit|rotate-keys
checkscanner screen ls|start|attach|logs|stop|restart
checkscanner token <username>[:<password>]   # or -u <username> [-p <password>]
```

### Running in screen

To keep the server running after you log out, start it in a detached GNU screen session:

```bash
checkscanner screen                     # Start a session named "checkscanner"
checkscanner screen front --port 9000   # Start a session named "front" with server options
checkscanner screen ls                  # List running sessions, their state and directory
checkscanner screen logs front [-n 100] # Show recent output without attaching
checkscanner screen attach front        # Attach (detach again with Ctrl+A D)
checkscanner screen restart front       # Restart with the same options and directory
checkscanner screen stop front          # Stop a session (--all stops every session)
```

The session name defaults to `checkscanner` for every subcommand. Sessions show as `checkscanner-<name>` in `screen -ls`.

### Scanning checks

1. Log in to the web interface with the admin credentials from `admin_credentials.txt`.
2. Add a scanner profile (web interface or `checkscanner profile add`) with the device's host and type.
3. Connect to the scanner and scan checks. Only one user can be connected to a given scanner at a time.

Supported devices:

| Type | Protocol |
|---|---|
| Magtek | Telnet + FTP |
| RDM | HTTPS (XML) |

### API

Swagger UI is available at `http://localhost:8000/docs` while the server is running. Authenticate with `POST /token` (or `checkscanner token <username>`) and send the returned JWT as `Authorization: Bearer <token>`.
