Metadata-Version: 2.4
Name: checkscanner
Version: 0.1.4
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

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)
```

## 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 |
