Metadata-Version: 2.4
Name: qualis-roku
Version: 0.5.1
Summary: Lightweight Python client for the Qualis Desk Roku machine API (connect, validate users, clear transactions).
Author: Qualis Desk
License: MIT
Keywords: roku,qualis,developer-portal,automation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-httpx>=0.30; extra == "dev"

# qualis-roku

Python **3.9+** helper for automating **Roku Developer Portal** workflows when your organization exposes a compatible **Qualis Desk–style HTTP API** (portal sign-in, test-user validation, clearing channel transactions from CI or tooling).

## Install

```bash
pip install qualis-roku
```

**From source** (development):

```bash
pip install -e "./packages/qualis_roku"
```

## Use cases

- **Pre-flight checks** — Confirm a QA email resolves to a portal test user for a given app (e.g. MAX / D+) before a test run.
- **Clean slate** — Void test-user purchases / entitlements on a channel before functional or billing-related tests.
- **Pipelines** — Drive the same flows from Jenkins, GitHub Actions, or internal runners without opening the browser UI.
- **Batch operations** — Loop over emails or products using the simple `(success, message)` API.

## Design

- **`connect()`** — Start (or queue) server-side portal sign-in; no required arguments if your deployment defines default apps via configuration.
- **`validate(email, product)`** — Resolve the email in the current portal context for that product slug.
- **`clear_txn(email, product)`** — Clear transactions for that email and product.

Each returns **`(True, message)`** or **`(False, message)`** so callers can branch without exceptions for normal failures.

Lower-level methods (`validate_users`, `clear_transactions`, `connect_and_wait`, …) return full JSON envelopes when you need structured details.

## Quick start

**Credentials and host** can come from **environment variables** (recommended—nothing secret in code) or be passed **explicitly** to the constructor. Your internal runbook names the exact variables; typical names look like a “Qualis base URL” and an “API credential” for your deployment.

**From environment** (set vars in the shell, CI secrets, or `.env` loaded by your app—do not commit secrets):

```python
from qualis_roku import QualisRokuClient

# Uses deployment-specific env vars when base_url / api_token are omitted.
with QualisRokuClient() as client:
    ok, msg = client.connect()
    if not ok:
        raise SystemExit(msg)
    ok_v, msg_v = client.validate("qa.user@company.com", "max")
    if not ok_v:
        raise SystemExit(msg_v)
    ok_c, msg_c = client.clear_txn("qa.user@company.com", "max")
    if not ok_c:
        raise SystemExit(msg_c)
```

**Explicit arguments** (useful for tests or when config is not on the process environment):

```python
with QualisRokuClient(
    base_url="https://your-qualis-host.example/qualis-desk",
    api_token="your-credential",
) as client:
    ok, msg = client.connect()
    ...
```

Omitted parameters fall back to environment; if both are missing, the client raises with a clear error. Passing **`base_url=`** or **`api_token=`** explicitly overrides the corresponding environment variable for that client instance.

## Command line

After install, the **`qualis-roku`** executable (or **`python -m qualis_roku`**) exposes the same flows without writing Python:

```bash
qualis-roku --help
qualis-roku connect
qualis-roku validate qa.user@company.com max
qualis-roku clear qa.user@company.com max
qualis-roku run qa.user@company.com max
```

Pass **`--base-url`** and **`--api-token`** or configure the environment variables described in your **internal** runbook. **`connect`** can write a small session file (default `./.qualis_roku_session`) so **`validate`** / **`clear`** can reuse the session; use **`--print-session-id-only`** for scripting.

Transient HTTP errors (429, 502–504) and retryable network failures are retried automatically with backoff.

Set **`QUALIS_ROKU_DEBUG=1`** (or pass **`debug=True`** to **`QualisRokuClient`**) for verbose debug logs on stderr.

## Requirements

- **Network**: HTTPS access from the machine running the client to your Qualis deployment.
- **`httpx`** (declared as a dependency).

## Documentation

- **Full reference** (operators + integrators): after install from source or a checkout, open **[`docs/DOCUMENTATION.md`](docs/DOCUMENTATION.md)** — complete env var list, API surface, CLI flags, retries, debug logging, and troubleshooting.
- Your organization may also maintain **internal runbooks** and HTTP samples for the server API; the PyPI page shows only this README.

## Security (general)

- Prefer **TLS** end-to-end.
- Keep credentials out of source control and logs; use your platform’s secret management.

## License

MIT.
