Metadata-Version: 2.4
Name: governed-http-sdk
Version: 0.1.1
Summary: Governed HTTP client SDK with Requests-like ergonomics and typed contracts
Author-email: Noir <devnull@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/no1rstack/artifact-verifier
Project-URL: Repository, https://github.com/no1rstack/artifact-verifier
Project-URL: Issues, https://github.com/no1rstack/artifact-verifier/issues
Keywords: http,sdk,governance,pydantic,requests,fastapi,typed
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3,>=2
Dynamic: license-file

# governed-http

A lightweight HTTP client with typed request/response contracts, request interception, and built-in request tracing.

It behaves like requests, but adds:

- Optional preflight checks before a request is sent
- Structured decision logging
- Pydantic-based request and response validation
- Dry-run mode (no network call)
- Pluggable transport for testing

Minimal dependencies: standard library + Pydantic.

## Why use this?

Most HTTP clients simply send requests and return responses.

This client adds a control layer:

- Every request can be inspected before execution
- Calls can be blocked based on host or custom rules
- Each request records what was attempted and what happened
- Responses can be validated against typed models

Useful for:

- Restricting outbound API calls
- Enforcing allowed hosts
- Building typed API wrappers
- Testing external integrations deterministically
- Capturing structured request traces

## Installation

```bash
pip install governed-http-sdk
```

## Quick Example

```python
from governed_http import Client

client = Client(
    base_url="https://api.example.com",
    allowed_hosts=["api.example.com"]
)

res = client.get("/status")
print(res.status_code)
```

## Typed Operations

```python
from pydantic import BaseModel
from governed_http import Client, Operation

class CreateThing(BaseModel):
    name: str

class Thing(BaseModel):
    id: int
    name: str

op = Operation(
    method="POST",
    path="/v1/things",
    request=CreateThing,
    response=Thing,
)

client = Client(
    base_url="https://api.example.com",
    allowed_hosts=["api.example.com"]
)

result: Thing = client.call(op, {"name": "example"})
```

The payload is validated before sending.
The response is parsed into a typed model.

## Dry Run (No Network)

```python
preview = client.dry_run_request("GET", "/v1/things")
print(preview)
```

Returns:

- Final URL
- Headers
- Request body
- Preflight decision

## Interceptors

Custom logic can be added before or after a request:

- Allow or deny outbound calls
- Modify headers
- Record additional metadata
- Enforce custom policy rules

## Testing with Mock Transport

The built-in `MockTransport` allows deterministic testing without network access.

## Summary

This package provides:

- A small, dependency-light HTTP client
- Typed request/response validation
- Optional outbound host restrictions
- Structured request tracing
- Pluggable transport for testing

It is designed for applications that need more control and visibility over outbound HTTP calls than a basic client provides.

## Install (editable)

```powershell
Push-Location artifact-verifier
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
Pop-Location
```
