Metadata-Version: 2.4
Name: mgf-apiprobe
Version: 0.2.0
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
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.13,>=0.11.0
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.

`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 in v0.1; OAuth2 later.
- **Matchers** — DSL for asserting response shape (format + semantic; IBAN, IMEI, E.164 included).

Status: **pre-publish** — v0.1.0 is the first scope-reduced release per `HANDOFF.md` §6 + `DEFERRED.md`. Everything past the core engine + ~18 checks + 3 CLI subcommands is deferred and tracked in [`DEFERRED.md`](DEFERRED.md).

## Install

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

Optional extras (forward-declared; see `DEFERRED.md` for ship-when):

```bash
pip install 'mgf-apiprobe[openapi]'   # OpenAPI ingestion (v0.2)
pip install 'mgf-apiprobe[faker]'     # Faker-backed factories (v0.2)
pip install 'mgf-apiprobe[signing]'   # Cassette signing (v0.3)
```

## Quick start (v0.1)

> Once v0.1.0 publishes; placeholder until the implementation lands.

```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 graduates to L2
by its own v1.0. See [`LIFT_CHECKLIST.md`](LIFT_CHECKLIST.md).

## Layout

| File | Purpose |
|---|---|
| [`DESIGN.md`](DESIGN.md) | The v0.3 design spec (≈ 1990 lines) with v0.4 sibling-decision addendum. WHAT we're building. |
| [`HANDOFF.md`](HANDOFF.md) | Integration plan. HOW it ships as a sibling of `mgf-common`. |
| [`DEFERRED.md`](DEFERRED.md) | Scope-reduction tracker. WHICH parts of WHAT ship in v0.1 vs. later. |
| [`LIFT_CHECKLIST.md`](LIFT_CHECKLIST.md) | Federation conformance acknowledgment. |
| [`CHANGELOG.md`](CHANGELOG.md) | Per-release notes. |

## License

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