From 50cb131cccb5748424cf606cec68f98fc3c669ea Mon Sep 17 00:00:00 2001 From: Facundo Farias Date: Wed, 18 Nov 2026 10:05:09 +0100 Subject: [PATCH] feat: add custom domain resource and branded URLs --- README.md | 5 ++- pyproject.toml | 2 +- src/pixelvault/_core.py | 2 +- src/pixelvault/client.py | 3 ++ src/pixelvault/custom_domains.py | 62 ++++++++++++++++++++++++++++++++ src/pixelvault/types.py | 39 ++++++++++++++++++++ tests/test_client.py | 45 +++++++++++++++++++++++ uv.lock | 2 +- 8 files changed, 156 insertions(+), 4 deletions(-) create mode 100644 src/pixelvault/custom_domains.py diff --git a/README.md b/README.md index 878533f..c044c1a 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ pv = PixelVault() # reads PIXELVAULT_API_KEY, or pass api_key="pv_live_..." # A path, bytes or a binary file object image = pv.images.upload("screenshot.png") -print(image["url"]) # https://img.pixelvault.dev/... +print(image.get("branded_url", image["url"])) # custom domain when ready, canonical fallback # Import from a URL, auto-delete after one hour pv.images.upload(url="https://example.com/a.png", expires_in=3600) @@ -98,6 +98,7 @@ async with AsyncPixelVault() as pv: | `exports.start()` / `wait(job_id)` / `download(job_id)` | Owner-authenticated tar export of non-expired images, videos, audio originals, available derivatives and `manifest.json` relationships | | `usage.get()` | Plan, usage, limits and what is left this month (including generation credits) | | `keys.list()` / `keys.create(label=, environment=)` / `keys.revoke(id)` | Manage your API keys (secret keys only) | +| `custom_domains.list()` / `.create(hostname)` / `.refresh(id)` / `.delete(id)` | Manage the active project's custom domains and inspect account plan capacity | | `register(email)` | Create an account, returns a first key once | | `device_login_start(email)` + `device_login_complete(email, code)` | Passwordless key minting | @@ -110,6 +111,8 @@ streaming manifests, summaries, chapters, show notes, promo copy, and storyboards remain unsupported. Sync and asyncio clients expose the same audio methods. +Media responses retain canonical `url` and include optional `branded_url` when the active project has a ready custom domain. Use the returned branded value; signed and transform query parameters are preserved. + ## Errors and retries Every failure raises `PixelVaultError` with `.status` (0 for network errors), `.code` (for example diff --git a/pyproject.toml b/pyproject.toml index c5e65a4..9e15dbc 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "pixelvault" -version = "0.7.0" +version = "0.8.0" description = "Official Python SDK for PixelVault, agent-first media hosting" readme = "README.md" license = "MIT" diff --git a/src/pixelvault/_core.py b/src/pixelvault/_core.py index 77dcba9..7757c3d 100644 --- a/src/pixelvault/_core.py +++ b/src/pixelvault/_core.py @@ -13,7 +13,7 @@ from .errors import PixelVaultError -__version__ = "0.7.0" +__version__ = "0.8.0" DEFAULT_BASE_URL = "https://api.pixelvault.dev" MAX_BACKOFF = 30.0 diff --git a/src/pixelvault/client.py b/src/pixelvault/client.py index a1fb74f..1862220 100644 --- a/src/pixelvault/client.py +++ b/src/pixelvault/client.py @@ -22,6 +22,7 @@ from .videos import AsyncVideos, Videos from .audio import AsyncAudioFiles, AudioFiles from .exports import AsyncExports, Exports +from .custom_domains import AsyncCustomDomains, CustomDomains from .types import ( ApiKey, CreatedKey, @@ -92,6 +93,7 @@ def __init__( self.audio = AudioFiles(self) self.usage = _Usage(self) self.keys = _Keys(self) + self.custom_domains = CustomDomains(self) def __enter__(self) -> "PixelVault": return self @@ -329,6 +331,7 @@ def __init__( self.audio = AsyncAudioFiles(self) self.usage = _AsyncUsage(self) self.keys = _AsyncKeys(self) + self.custom_domains = AsyncCustomDomains(self) async def __aenter__(self) -> "AsyncPixelVault": return self diff --git a/src/pixelvault/custom_domains.py b/src/pixelvault/custom_domains.py new file mode 100644 index 0000000..b5a9425 --- /dev/null +++ b/src/pixelvault/custom_domains.py @@ -0,0 +1,62 @@ +from __future__ import annotations + +from typing import Any, cast +from urllib.parse import quote + +from ._core import Request +from .types import CustomDomain, CustomDomainList + + +def _seg(value: str) -> str: + return quote(value, safe="") + + +class CustomDomains: + def __init__(self, client: Any) -> None: + self._c = client + + def list(self) -> CustomDomainList: + """List domains on the active project and account-wide plan capacity.""" + return cast(CustomDomainList, self._c._send(Request("GET", "/v1/custom-domains"))) + + def create(self, hostname: str) -> CustomDomain: + """Attach a customer-owned hostname and return its required DNS records.""" + body = self._c._send(Request("POST", "/v1/custom-domains", json={"hostname": hostname})) + return cast(CustomDomain, body["data"]) + + def refresh(self, domain_id: str) -> CustomDomain: + """Re-check DNS and certificate state after records change.""" + body = self._c._send( + Request("POST", f"/v1/custom-domains/{_seg(domain_id)}/refresh") + ) + return cast(CustomDomain, body["data"]) + + def delete(self, domain_id: str) -> None: + """Remove a custom domain. Canonical PixelVault URLs keep working.""" + self._c._send(Request("DELETE", f"/v1/custom-domains/{_seg(domain_id)}")) + + +class AsyncCustomDomains: + def __init__(self, client: Any) -> None: + self._c = client + + async def list(self) -> CustomDomainList: + return cast( + CustomDomainList, + await self._c._send(Request("GET", "/v1/custom-domains")), + ) + + async def create(self, hostname: str) -> CustomDomain: + body = await self._c._send( + Request("POST", "/v1/custom-domains", json={"hostname": hostname}) + ) + return cast(CustomDomain, body["data"]) + + async def refresh(self, domain_id: str) -> CustomDomain: + body = await self._c._send( + Request("POST", f"/v1/custom-domains/{_seg(domain_id)}/refresh") + ) + return cast(CustomDomain, body["data"]) + + async def delete(self, domain_id: str) -> None: + await self._c._send(Request("DELETE", f"/v1/custom-domains/{_seg(domain_id)}")) diff --git a/src/pixelvault/types.py b/src/pixelvault/types.py index cd7e265..ba0ce1d 100644 --- a/src/pixelvault/types.py +++ b/src/pixelvault/types.py @@ -13,6 +13,8 @@ class Image(TypedDict): id: str url: str + #: Same asset on the project's active custom domain, when configured and ready. + branded_url: NotRequired[str] mime_type: str size: int width: Optional[int] @@ -61,6 +63,7 @@ class ImagePage(TypedDict): class SignedUrl(TypedDict): url: str + branded_url: NotRequired[str] expires: int @@ -116,6 +119,38 @@ class Usage(TypedDict): video_enrichment: NotRequired[VideoSecondsUsage] +class CustomDomainVerification(TypedDict): + type: Literal["TXT"] + name: str + value: str + + +class CustomDomain(TypedDict): + id: str + project_id: str + hostname: str + status: str + hostname_status: str + certificate_status: str + ready: bool + cname_target: str + ownership_verification: Optional[CustomDomainVerification] + created_at: str + updated_at: str + + +class CustomDomainCapacity(TypedDict): + limit: int + total: int + project_total: int + cname_target: str + + +class CustomDomainList(TypedDict): + data: List[CustomDomain] + meta: CustomDomainCapacity + + class ApiKey(TypedDict): id: str type: str @@ -157,6 +192,7 @@ class Video(TypedDict): kind: str url: str original_url: str + branded_url: NotRequired[str] visibility: str mime_type: str size: int @@ -217,6 +253,7 @@ class Audio(TypedDict): kind: Literal["audio"] url: str original_url: str + branded_url: NotRequired[str] visibility: Literal["public", "private"] mime_type: Literal["audio/mpeg", "audio/wav", "audio/mp4", "audio/ogg"] size: int @@ -244,6 +281,7 @@ class AudioPage(TypedDict): class AudioSignedUrl(TypedDict): url: str + branded_url: NotRequired[str] original_url: str expires: int visibility: Literal["public", "private"] @@ -314,6 +352,7 @@ class ExportWaitResult(TypedDict): class VideoSignedUrls(TypedDict): url: str + branded_url: NotRequired[str] enrichment: Dict[str, Any] expires: int poster_url: NotRequired[str] diff --git a/tests/test_client.py b/tests/test_client.py index c3ac005..274859c 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -963,3 +963,48 @@ def handler(req): started = await pv.exports.start() result = await pv.exports.wait(started["job_id"], timeout=0) assert result["job"]["status"] == "processing" and result["timed_out"] is True + +def test_custom_domains_manage_encoded_ids_and_capacity(): + seen = [] + domain = { + "id": "dom/1", + "project_id": "proj_1", + "hostname": "media.example.com", + "status": "active", + "hostname_status": "active", + "certificate_status": "active", + "ready": True, + "cname_target": "custom.pvcdn.dev", + "ownership_verification": None, + "created_at": "2026-11-18T00:00:00Z", + "updated_at": "2026-11-18T00:00:00Z", + } + + def handler(req): + seen.append(req) + if req.method == "GET": + return httpx.Response( + 200, + json={ + "data": [domain], + "meta": { + "limit": 1, + "total": 1, + "project_total": 1, + "cname_target": "custom.pvcdn.dev", + }, + }, + ) + if req.method == "DELETE": + return httpx.Response(200, json={"data": {"id": "dom/1", "deleted": True}}) + return httpx.Response(200, json={"data": domain}) + + domains = make(handler).custom_domains + assert domains.list()["meta"]["limit"] == 1 + assert domains.create("media.example.com")["ready"] is True + assert domains.refresh("dom/1")["hostname"] == "media.example.com" + domains.delete("dom/1") + + assert json.loads(seen[1].content) == {"hostname": "media.example.com"} + assert str(seen[2].url).endswith("/v1/custom-domains/dom%2F1/refresh") + assert str(seen[3].url).endswith("/v1/custom-domains/dom%2F1") diff --git a/uv.lock b/uv.lock index bfaf19a..b119a5d 100644 --- a/uv.lock +++ b/uv.lock @@ -516,7 +516,7 @@ wheels = [ [[package]] name = "pixelvault" -version = "0.7.0" +version = "0.8.0" source = { editable = "." } dependencies = [ { name = "httpx" },