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 |
