# mgf-apiprobe

REST API verification — typed probes, checks, and findings.

> **Shape:** Federation sibling of `mgf-common`. The current
> `mgf-common` pin window is shown in this package's
> [Codeberg registry](https://codeberg.org/magogi-admin/mgf-apiprobe) —
> sourced from `pyproject.toml` at release time, so this README
> can't go stale. (Per v2.6 DOC-01 / project-shape taxonomy.
> PAPER-38.)

`mgf-apiprobe` is the API-verification sibling of [`mgf-common`](https://codeberg.org/magogi-admin/mgf-common).
It builds on `mgf-common`'s settings, error, and observability primitives,
and adds:

- **Probes** — typed descriptions of an HTTP request + the expected response shape.
- **Checks** — pluggable verifiers that emit structured Findings (code, severity, root_cause, evidence, remediation).
- **Suites** — collections of probes that run async and produce a Report.
- **AuthFlows** — bearer / basic / api-key / cookie / custom; OAuth2 is a future add.
- **Matchers** — DSL for asserting response shape (format + semantic; IBAN, IMEI, E.164 included).

## Install

```bash
pip install mgf-apiprobe
```

Optional extras (forward-declared):

```bash
pip install 'mgf-apiprobe[openapi]'   # OpenAPI ingestion
pip install 'mgf-apiprobe[faker]'     # Faker-backed factories
pip install 'mgf-apiprobe[signing]'   # Cassette signing
```

## Quick start

```python
from mgf.apiprobe import Probe, Suite, BearerAuth

probe = (
    Probe.get("https://httpbin.org/get")
    .with_auth(BearerAuth(token="..."))
    .expects_status(200)
    .expects_json_shape({"url": str, "headers": dict})
)

suite = Suite([probe])
report = await suite.run()
print(report.to_human())
```

## Standards

**Conformance: L2** per [`mgf-standard/docs/standards/`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/). Per-rule audit ledger: [`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`](docs/inprogress/MGF_STANDARDS_CONFORMANCE.md).

The L2 floor means every federation **MUST** rule applies, evidenced by the tracker: BaseAppSettings, AppError hierarchy, structured logging, redaction, py.typed, SemVer with the 0.x carve-out, ≥80% coverage gate, no secrets in cassettes/logs. The earlier "L1 — Production-Ready" framing in this README was the pre-v2.7 nomenclature; the current standards (per [`docs/standards/README.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/README.md) §"Conformance levels for projects") define **L1 — Lite** / **L2 — Standard** / **L3 — Strict** with L2 as the federation-sibling baseline.

## Layout

| File | Purpose |
|---|---|
| [`DESIGN.md`](DESIGN.md) | The design spec (≈ 1990 lines). WHAT we're building. |
| [`HANDOFF.md`](HANDOFF.md) | Integration plan. HOW it ships as a sibling of `mgf-common`. |
| [`LIFT_CHECKLIST.md`](LIFT_CHECKLIST.md) | Federation conformance acknowledgment. |

## License

MIT. See [`LICENSE`](LICENSE) (TBD).
