# BBEye Python SDK

`bbeye` is the Python SDK used by [BBEye](https://github.com/OpenDebates/BBEye) decrypt scripts.

It provides:

- `Request` / `Response` wrappers
- `Result` helpers for text, JSON, hex, and protobuf views
- `console()` for printing messages back into the BBEye console
- `test()` for local script debugging
- `python -m bbeye your_script.py` as the runtime entrypoint used by BBEye

## Install

```bash
pip install bbeye
```

## Basic example

```python
from bbeye import Result, console


def onResponse(response):
    console("url:", response.url)
    return Result.showText(response.body)
```

## JSON example

```python
from bbeye import Result


def onRequest(request):
    return Result.showJson(request.json())
```

## Local test

```python
from bbeye import Result, test


def onResponse(response):
    return Result.showText(response.body)


if __name__ == "__main__":
    test(
        onResponse,
        url="https://example.com/api/demo",
        body=b'{"ok":true}',
        direction="response",
    )
```

## Runtime model

BBEye invokes user scripts like this:

```bash
python3 -m bbeye your_script.py
```

The user script should define one or both of:

- `onRequest(request)`
- `onResponse(response)`

Each callback can return:

- `Result.showText(...)`
- `Result.showJson(...)`
- `Result.showHex(...)`
- `Result.showProtobuf(...)`
- `Result.error(...)`

Returning raw `str` or `bytes` is also supported and will be treated as text.

## API summary

### `Request` / `Response`

Common properties:

- `url`
- `headers`
- `body`
- `direction`

Common methods:

- `text(encoding="utf-8")`
- `json()`
- `header(name)`

### `Result`

- `Result.showText(data)`
- `Result.showJson(data)`
- `Result.showHex(data)`
- `Result.showProtobuf(data)`
- `Result.error(message)`

### Helpers

- `console(*args, **kwargs)`
- `test(func, url=..., headers=..., body=..., direction=...)`

## Publishing

For maintainers:

```bash
cd python-sdk
./publish.sh check
./publish.sh testpypi
./publish.sh pypi
```

Credentials should be provided via:

- `TWINE_USERNAME` / `TWINE_PASSWORD`, or
- `~/.pypirc`
