Metadata-Version: 2.4
Name: bbeye
Version: 0.1.0
Summary: Python SDK for BBEye MITM proxy decrypt scripts
Author: BBEye Team
License-Expression: MIT
Project-URL: Homepage, https://github.com/OpenDebates/BBEye
Project-URL: Repository, https://github.com/OpenDebates/BBEye
Project-URL: Documentation, https://github.com/OpenDebates/BBEye/tree/main/doc
Keywords: bbeye,mitm,proxy,decrypt,sdk,http
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown

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