Metadata-Version: 2.4
Name: qualis-roku
Version: 0.4.0
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

Configure the client using the **base URL** and **credentials** supplied by your platform team. Your organization’s runbook describes how to set those safely (environment variables, secret store, etc.—**do not commit secrets**).

```python
from qualis_roku import QualisRokuClient

with QualisRokuClient(
    base_url="https://your-qualis-host.example/qualis-desk",
    api_token="...",  # or use your team’s recommended env/config pattern
) 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)
```

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

## Requirements

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

## Documentation

- **Operators and integrators** using Qualis Desk should follow **internal documentation** (runbooks, machine API samples) provided by your organization—not everything is duplicated here on PyPI.

## Security (general)

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

## License

MIT.
