Metadata-Version: 2.5
Name: smoke-sdk
Version: 0.1.0
Summary: Python SDK for the Smoke public API v1 and webhook signatures
Project-URL: Homepage, https://github.com/Aircraft-IT/smoke-sdk-python
Project-URL: Source, https://github.com/Aircraft-IT/smoke-sdk-python
Project-URL: Issues, https://github.com/Aircraft-IT/smoke-sdk-python/issues
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Smoke SDK for Python

Client for the Smoke public API v1 and helper to verify Smoke webhook signatures. Python 3.9 or
later; standard library only.

```sh
pip install smoke-sdk
```

## API

Create an **integration token** (Admins, after turning on *API and webhooks* in the workspace
settings) or a personal token on the API tokens page. Keep it in a secret store, never in code.

```python
import os
from smoke_sdk import SmokeClient

smoke = SmokeClient(os.environ["SMOKE_TOKEN"], "https://api.<your Smoke domain>/v1")

# Every P1 and P2 finding that still needs work, page by page.
for f in smoke.iter_findings(priority="P1,P2", status="open,in_progress"):
    print(f["priority"], f["package"], f["version"], f["url"])

# Assign one to a member (user id from smoke.list_members()).
smoke.update_finding(finding_id, status="in_progress", assigneeId=user_id)

# Upload the inventory at every release, then wait for the result.
with open("package-lock.json", "rb") as fh:
    snap = smoke.upload_inventory(
        asset_id, [("package-lock.json", fh.read())], release="v1.4.2", commit=os.environ["GIT_SHA"]
    )
done = smoke.wait_for_match(snap["id"])
if (done["findings"] or {}).get("unresolved", {}).get("p1", 0) > 0:
    raise SystemExit(1)
```

Retries: 429, 5xx and network errors are retried up to 3 times with backoff, honouring
`Retry-After`; uploads send the same `Idempotency-Key` on every attempt. Errors are raised as
`SmokeApiError` with `status`, `code` (stable, see the API guide), `details` and `request_id`.

## Webhooks

```python
from smoke_sdk import verify_webhook_signature

# Flask: request.get_data() is the raw body.
@app.post("/smoke")
def smoke_webhook():
    if not verify_webhook_signature(
        request.get_data(), request.headers.get("X-Smoke-Signature"), os.environ["SMOKE_WEBHOOK_SECRET"]
    ):
        return "", 401
    event = request.get_json()
    # Deduplicate by event["id"] (X-Smoke-Event-Id): a resent event keeps its id.
    return "", 204
```

## Versions

This SDK follows semver and targets API `v1`, which only changes additively. `smoke_sdk/types.py`
is generated from `openapi.json` (`python3 tools/generate_types.py`), a copy of the public API
document (`https://api.<domain>/v1/openapi.json`); a test checks they agree.

## Source and releases

This repository is published at <https://github.com/Aircraft-IT/smoke-sdk-python> when a version
is released: each release is a tag `v<version>` on `main`, and pushing it runs
[the publish workflow](.github/workflows/publish.yml), which tests, builds and publishes the
package to PyPI through trusted publishing, with attestations. On pypi.org each file shows the
commit and workflow it was built from. Development happens in Smoke's own repository, so `main`
here moves only at releases.

Issues are welcome. Pull requests are not merged directly; a change we take is made in the
development repository and appears here with the next release. Contributions are under the
Apache License 2.0, like the rest of the repository.

## License

Apache-2.0
