Metadata-Version: 2.4
Name: conduit-client
Version: 0.1.0
Summary: Python client for the Conduit / Mega API gateway.
Author: Chelsea
License: MIT
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# conduit-client

Python client for the Conduit / Mega API gateway at
`https://api.cowtunnel.com`.

The first release intentionally focuses on the stable gateway surface:

- health
- service catalog and service health
- current actor information
- API key lifecycle
- admin key/audit inspection
- custom namespace registration for future provider facades

Provider-specific methods should be added after their concrete live paths and
request/response contracts are confirmed.

## Install

```sh
python -m pip install -e .
```

## Configuration

The client reads these environment variables:

```text
MEGA_API_BASE_URL  default: https://api.cowtunnel.com
MEGA_API_KEY       API key for protected endpoints
MEGA_API_TIMEOUT   default: 30
```

The default auth header is:

```text
Authorization: Bearer <MEGA_API_KEY>
```

`X-API-Key` is also supported:

```python
from conduit import Client

client = Client(api_key="...", auth_header="x-api-key")
```

## Quick Start

```python
from conduit import Client

client = Client.from_env()

print(client.health())
print(client.auth.me())
print(client.services.list())
print(client.services.health())
```

## API Keys

```python
created = client.keys.create(
    display_name="automation",
    scopes=["gateway:read"],
)

print(created["key_prefix"])

client.keys.revoke(created["key_prefix"])
```

The raw created key is returned by the gateway once. Do not log it.

## Admin

```python
logs = client.admin.audit(limit=10, result="success")
keys = client.admin.keys()
```

These calls require the relevant scopes on the API key and key owner.

## Raw Requests

The typed provider namespaces are intentionally not filled in until provider
operation paths are confirmed. Advanced callers can still use the shared
transport:

```python
data = client.request("GET", "/dns/servers/default/status")
```

Prefer typed methods once they exist.

## Extensibility

Custom namespaces can be registered without changing the core client:

```python
from conduit.namespaces import Namespace


class CustomNamespace(Namespace):
    def status(self):
        return self._get("/custom/status")


client.register_namespace("custom", CustomNamespace)
print(client.custom.status())
```

## Safety

Destructive provider methods should require explicit confirmation arguments
when they are added. The current core gateway client does not hide write
operations behind convenience helpers.

