Metadata-Version: 2.4
Name: conduit-client
Version: 0.2.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 client covers the stable gateway surface:

- health
- Swagger UI/OpenAPI retrieval
- service catalog and service health
- auth login/callback and current actor information
- API key lifecycle
- admin key/audit inspection
- key-management UI HTML retrieval
- SMS/MMS facade helpers
- MeTube ingestion facade helpers
- Jellyfin media library facade helpers
- Transmission torrent facade helpers
- Proxmox compute facade helpers
- BIND9 DNS facade helpers
- custom namespace registration for future provider facades

Provider request/response bodies are intentionally permissive where backend
schemas are still evolving.

## Install

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

For Gitea package registry publishing/install instructions, see
`PUBLISHING.md`.

## 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.openapi())
print(client.auth.me())
print(client.services.list())
print(client.services.health())
```

## Provider Examples

SMS with the configured default sender DID:

```python
client.sms.send("7068442742", "hi")
```

SMS with an explicit sender DID:

```python
client.sms.send("7068442742", "hi", did="15551234567")
```

MMS:

```python
client.sms.send_mms(
    "7068442742",
    "image",
    media1="https://example.test/image.png",
)
```

DNS:

```python
client.dns.server_status()
client.dns.zone("example.org")
client.dns.batch_update_records("example.org", [
    {"action": "add", "name": "www", "type": "A", "ttl": 300, "value": "192.0.2.10"},
])
```

Media:

```python
client.media.ingest.jobs()
client.media.ingest.create_job("https://example.test/video")
client.media.library.search(term="matrix", limit=5)
```

Torrents:

```python
client.torrents.list()
client.torrents.start(7)
```

Compute:

```python
client.compute.resources(type="vm")
client.compute.start_vm(100)
```

Destructive helpers require explicit confirmation:

```python
client.dns.delete_zone("example.org", confirm="example.org")
client.compute.delete_vm(100, confirm=100)
client.torrents.remove(7, confirm=7, delete_local_data=False)
```

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