Metadata-Version: 2.4
Name: mgf-apiprobe
Version: 0.5.1
Summary: REST API verification — typed probes, checks, and findings. Sibling of mgf-common.
Project-URL: Homepage, https://codeberg.org/magogi-admin/mgf_apiprobe
Project-URL: Issues, https://codeberg.org/magogi-admin/mgf_apiprobe/issues
Author: Bassam Alsanie, mgf-apiprobe contributors
License: MIT
License-File: LICENSE
Keywords: api,contract-testing,httpx,openapi,rest,verification
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: jmespath>=1.0
Requires-Dist: jsonpath-ng>=1.6
Requires-Dist: mgf-common<0.38,>=0.37
Requires-Dist: pydantic>=2.7
Provides-Extra: dev
Requires-Dist: coverage>=7.0; extra == 'dev'
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: import-linter>=2.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: faker
Requires-Dist: faker>=25; extra == 'faker'
Provides-Extra: openapi
Requires-Dist: openapi-core>=0.19; extra == 'openapi'
Provides-Extra: signing
Requires-Dist: cryptography>=42; extra == 'signing'
Description-Content-Type: text/markdown

# 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
> [PyPI metadata](https://pypi.org/project/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

This package targets `mgf-common`'s L1 — Production-Ready standards
day-one (BaseAppSettings, AppError, structured logging, redaction, py.typed,
semver, ≥80% coverage, no secrets in cassettes/logs). It will graduate to L2
as the sibling matures. See [`LIFT_CHECKLIST.md`](LIFT_CHECKLIST.md).

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