185 lines
4.3 KiB
Markdown
185 lines
4.3 KiB
Markdown
# conduit-client
|
|
|
|
A typed Python client for the [Conduit](https://conduit.librewiki.org/doku.php?id=examples) unified API gateway.
|
|
|
|
## Features
|
|
|
|
- Synchronous and asynchronous clients (`ConduitClient` and `AsyncConduitClient`).
|
|
- Pydantic v2 request/response models.
|
|
- Covers every documented Conduit endpoint across gateway, SMS/MMS, media, torrents, wiki, compute, and DNS façades.
|
|
- Clean error handling with typed exceptions.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pip install conduit-client
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```python
|
|
from conduit_client import ConduitClient
|
|
|
|
client = ConduitClient("mega_sk_live_<prefix>_<secret>")
|
|
me = client.gateway.me()
|
|
print(me.scopes)
|
|
```
|
|
|
|
## Async usage
|
|
|
|
```python
|
|
import asyncio
|
|
from conduit_client import AsyncConduitClient
|
|
|
|
async def main():
|
|
async with AsyncConduitClient("mega_sk_live_<prefix>_<secret>") as client:
|
|
me = await client.gateway.me()
|
|
print(me.scopes)
|
|
|
|
asyncio.run(main())
|
|
```
|
|
|
|
## Per-façade examples
|
|
|
|
### Gateway
|
|
|
|
```python
|
|
from conduit_client import ConduitClient
|
|
from conduit_client.models.common import CreateKeyRequest
|
|
from conduit_client.models.gateway import AuditLogQuery
|
|
|
|
client = ConduitClient("mega_sk_live_<prefix>_<secret>")
|
|
|
|
# API keys
|
|
keys = client.gateway.list_keys()
|
|
new_key = client.gateway.create_key(CreateKeyRequest(display_name="ci", scopes=["sms:send"]))
|
|
print(new_key.key) # one-time secret
|
|
|
|
# Audit log
|
|
entries = client.gateway.admin_audit(AuditLogQuery(scope="sms:send", limit=50))
|
|
```
|
|
|
|
### SMS / MMS
|
|
|
|
```python
|
|
from conduit_client.models.sms import SendSmsRequest, SendMmsRequest
|
|
|
|
sms_id = client.sms.send_sms(SendSmsRequest(did="5550100", dst="5550200", message="hi"))
|
|
print(sms_id.id)
|
|
|
|
mms_id = client.sms.send_mms(
|
|
SendMmsRequest(
|
|
did="5550100",
|
|
dst="5550200",
|
|
message="pic",
|
|
media1="https://example.com/photo.jpg",
|
|
)
|
|
)
|
|
```
|
|
|
|
### Media ingestion (MeTube)
|
|
|
|
```python
|
|
from conduit_client.models.media_ingest import CreateIngestJobRequest
|
|
|
|
job = client.media_ingest.create_job(
|
|
CreateIngestJobRequest(url="https://www.youtube.com/watch?v=abc", quality="best")
|
|
)
|
|
print(job.id, job.status)
|
|
```
|
|
|
|
### Media library (Jellyfin)
|
|
|
|
```python
|
|
from conduit_client.models.media_library import LibraryLoginRequest, LibrarySearchQuery
|
|
|
|
client.media_library.login(LibraryLoginRequest(username="user", password="pw"))
|
|
results = client.media_library.search(LibrarySearchQuery(term="Inception"))
|
|
```
|
|
|
|
### Torrents (Transmission)
|
|
|
|
```python
|
|
from conduit_client.models.torrents import AddTorrentRequest
|
|
|
|
client.torrents.add(AddTorrentRequest(url="magnet:?xt=urn:btih:...", paused=False))
|
|
client.torrents.list(fields=["id", "name"])
|
|
```
|
|
|
|
### Wiki (DokuWiki)
|
|
|
|
```python
|
|
from conduit_client.models.wiki import WriteWikiPageRequest
|
|
|
|
page = client.wiki.get_raw("namespace:page")
|
|
client.wiki.write("namespace:page", WriteWikiPageRequest(text="updated content"))
|
|
```
|
|
|
|
### Compute (Proxmox)
|
|
|
|
```python
|
|
from conduit_client.models.compute import CreateVmRequest, ComputeTicketRequest
|
|
|
|
ticket = client.compute.auth_ticket(ComputeTicketRequest(username="root", password="pw"))
|
|
print(ticket.ticket)
|
|
|
|
# Create a VM; extra Proxmox fields are forwarded as-is.
|
|
client.compute.create_vm(
|
|
CreateVmRequest(node="pve", vmid=100, cores=2, memory=2048, storage="local-lvm")
|
|
)
|
|
client.compute.start_vm(100)
|
|
```
|
|
|
|
### DNS (BIND9)
|
|
|
|
```python
|
|
from conduit_client.models.dns import (
|
|
AddZoneRequest,
|
|
BatchRecordUpdate,
|
|
BatchUpdateRecordsRequest,
|
|
)
|
|
|
|
client.dns.create_zone(AddZoneRequest(zone="example.com", klass="IN"))
|
|
client.dns.batch_update_records(
|
|
"example.com",
|
|
BatchUpdateRecordsRequest(
|
|
updates=[
|
|
BatchRecordUpdate(op="add", name="www", ttl=300, rtype="A", rdata="1.2.3.4")
|
|
]
|
|
),
|
|
)
|
|
client.dns.reload_server("default")
|
|
```
|
|
|
|
## Error handling
|
|
|
|
```python
|
|
from conduit_client import ConduitClient, AuthenticationError, NotFoundError
|
|
|
|
client = ConduitClient("mega_sk_live_<prefix>_<secret>")
|
|
|
|
try:
|
|
client.sms.delete_sms(999999)
|
|
except NotFoundError as exc:
|
|
print(exc.status_code, exc.response_body)
|
|
except AuthenticationError as exc:
|
|
print("Invalid API key", exc.status_code)
|
|
```
|
|
|
|
## Configuration
|
|
|
|
```python
|
|
from conduit_client import ConduitClient
|
|
|
|
client = ConduitClient(
|
|
"mega_sk_live_<prefix>_<secret>",
|
|
base_url="https://api.cowtunnel.com",
|
|
timeout=60.0,
|
|
max_retries=2,
|
|
)
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|