stackshift 0.1.0__tar.gz → 1.0.0__tar.gz

{stackshift-0.1.0 → stackshift-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackshift
-Version: 0.1.0
+Version: 1.0.0
 Summary: Official Python SDK for StackShift.
 Requires-Python: >=3.9
 Requires-Dist: requests>=2.31

stackshift-1.0.0/README.md

@@ -0,0 +1,207 @@
+# StackShift Python SDK
+
+Official Python SDK for StackShift.
+
+## Install
+
+```bash
+pip install stackshift
+```
+
+## Send email
+
+```python
+from stackshift import StackShift
+
+stackshift = StackShift()
+
+message = stackshift.mail.send(
+    from_="StackShift <noreply@mail.stackshift.cloud>",
+    to="ada@example.com",
+    subject="Welcome",
+    text="Welcome to StackShift.",
+    idempotency_key="welcome:user_123",
+)
+
+print(message["id"], message["status"], message["idempotencyStatus"])
+```
+
+Inspect message status:
+
+```python
+messages = stackshift.mail.messages.list(status="mta_accepted", limit=20)
+detail = stackshift.mail.messages.get(messages["data"][0]["id"])
+attempts = stackshift.mail.messages.attempts(detail["id"])
+logs = stackshift.mail.messages.logs(detail["id"])
+```
+
+`mta_accepted` means the message was accepted by StackShift's outbound MTA. It does not mean recipient-MX acceptance, inbox placement, opens, clicks, or spam placement. Recipient records later transition independently to `delayed`, `delivered`, `bounced`, `failed`, `suppressed`, or `complained`.
+
+## Events and webhooks
+
+```python
+events = stackshift.mail.events.list(
+    type="mail.message.bounced",
+    message_id="msg_123",
+    limit=20,
+)
+
+event = stackshift.mail.events.get("evt_123")
+timeline = stackshift.mail.messages.timeline("msg_123")
+
+webhook = stackshift.mail.webhooks.create(
+    url="https://example.com/stackshift-mail",
+    event_types=["mail.message.bounced", "mail.otp.verified"],
+)
+print(webhook["id"], webhook["secret"])  # Secret is only returned on create/rotate.
+
+deliveries = stackshift.mail.webhooks.deliveries(webhook["id"], status="failed")
+retried = stackshift.mail.webhooks.retry_delivery(deliveries["data"][0]["id"])
+```
+
+Verify a webhook signature before processing the payload:
+
+```python
+valid = stackshift.mail.webhooks.verify_signature(
+    raw_body=request.get_data(),
+    signature_header=request.headers.get("StackShift-Signature"),
+    timestamp_header=request.headers.get("StackShift-Timestamp"),
+    secret=os.environ["STACKSHIFT_WEBHOOK_SECRET"],
+)
+```
+
+Webhook handlers should be idempotent. StackShift retries non-2xx responses. Delivery events do not include full email bodies or OTP codes by default.
+
+## Send a template
+
+Templates are rendered by StackShift servers. The Python SDK only calls the REST API.
+
+```python
+stackshift.mail.templates.create(
+    name="Welcome Email",
+    slug="welcome-email",
+    subject="Welcome, {{name}}",
+    text="Welcome, {{name}}",
+)
+
+preview = stackshift.mail.templates.preview(
+    "welcome-email",
+    data={"name": "Ada"},
+)
+
+message = stackshift.mail.send_template(
+    template="welcome-email",
+    to="ada@example.com",
+    from_="Acme <noreply@acme.com>",
+    data={"name": "Ada"},
+    idempotency_key="welcome:user_123",
+)
+```
+
+Missing variables fail before a message is queued. Template sends use the same sender-domain, suppression, idempotency, Durable Jobs, and Postfix handoff pipeline as `mail.send`.
+
+## Bounces and suppressions
+
+```python
+suppressions = stackshift.mail.suppressions.list()
+
+manual = stackshift.mail.suppressions.create(
+    email="bad@example.com",
+    reason="manual",
+)
+
+stackshift.mail.suppressions.delete(manual["id"])
+
+bounces = stackshift.mail.bounces.list(type="hard")
+message_bounces = stackshift.mail.messages.bounces("msg_123")
+```
+
+Hard bounces are automatically suppressed by the backend. Suppressions are workspace scoped and checked before a message is queued.
+
+## Verify a sending domain
+
+```python
+domain = stackshift.mail.domains.create("acme.com")
+print(domain["records"])
+
+stackshift.mail.domains.verify(domain["id"])
+
+message = stackshift.mail.send(
+    from_="Acme <noreply@acme.com>",
+    to="user@example.com",
+    subject="Welcome",
+    html="<h1>Welcome</h1>",
+    text="Welcome",
+)
+```
+
+Add the returned SPF, DKIM, and return-path DNS records before verification. DMARC is recommended unless your environment sets `MAIL_DMARC_REQUIRED=true`. DNS propagation can take time.
+
+## Upload an asset
+
+```python
+from stackshift import StackShift
+
+stackshift = StackShift()
+
+asset = stackshift.assets.upload(
+    "avatar.png",
+    folder="avatars",
+    visibility="public",
+    metadata={"user_id": "user_123"},
+)
+
+print(asset["url"])
+```
+
+You do not pass a deployed StackShift project ID. The API key identifies the StackShift account, and StackShift resolves the default asset space internally.
+
+## Private asset URL
+
+```python
+signed = stackshift.assets.signed_url(
+    asset["id"],
+    expires_in="10m",
+    max_downloads=1,
+)
+
+print(signed["url"])
+```
+
+## Image transformations
+
+Use built-in presets or create your own named transformations.
+
+```python
+from stackshift import StackShift, asset_transform_options, get_asset_transform_preset
+
+stackshift = StackShift()
+hero = get_asset_transform_preset("hero")
+hero_options = asset_transform_options(hero)
+
+stackshift.assets.create_transformation(hero["name"], **hero_options)
+
+named = stackshift.assets.named_url("asset_123", hero["name"])
+signed = stackshift.assets.signed_transform_url("asset_123", **hero_options, expiresIn="10m")
+
+stackshift.assets.delete_transformation("old-preset")
+print(named, signed["url"])
+```
+
+## Direct browser uploads
+
+Create the upload session on your Python backend:
+
+```python
+upload = stackshift.assets.signed_upload_url(
+    bucket="avatars",
+    key="users/user_123.png",
+    visibility="public",
+    expiresIn="10m",
+    maxBytes=5_000_000,
+)
+```
+
+Then upload the browser `File` to `upload["url"]` from your frontend. Do not expose your StackShift API key to browser code.
+
+The SDK only talks to the StackShift REST API. Storage placement, replication, disks, and repair are StackShift internals.

{stackshift-0.1.0 → stackshift-1.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stackshift"
-version = "0.1.0"
+version = "1.0.0"
 description = "Official Python SDK for StackShift."
 requires-python = ">=3.9"
 dependencies = ["requests>=2.31"]

stackshift-1.0.0/stackshift/__init__.py

@@ -0,0 +1,40 @@
+from .client import StackShift
+from .assets import ASSET_TRANSFORM_PRESETS, AssetsClient, asset_transform_options, asset_transform_spec, get_asset_transform_preset
+from .mail import (
+    MailClient,
+    MailDomainsClient,
+    MailOTPChallengesClient,
+    MailOTPClient,
+    MailTemplatesClient,
+)
+from .mail_reputation import MailLimitsClient, MailReputationClient, MailReputationEventsClient
+from .mail_events_webhooks import MailEventsClient, MailWebhooksClient, verify_webhook_signature
+from .mail_streams import MailStreamsClient
+from .mail_campaigns import MailAudiencesClient, MailCampaignsClient
+from .mail_exports import MailExportsClient
+from .projects import ProjectsClient
+
+__all__ = [
+    "StackShift",
+    "ASSET_TRANSFORM_PRESETS",
+    "AssetsClient",
+    "MailClient",
+    "MailDomainsClient",
+    "MailEventsClient",
+    "MailLimitsClient",
+    "MailOTPClient",
+    "MailOTPChallengesClient",
+    "MailReputationClient",
+    "MailReputationEventsClient",
+    "MailTemplatesClient",
+    "MailWebhooksClient",
+    "MailStreamsClient",
+    "MailAudiencesClient",
+    "MailCampaignsClient",
+    "MailExportsClient",
+    "ProjectsClient",
+    "asset_transform_options",
+    "asset_transform_spec",
+    "get_asset_transform_preset",
+    "verify_webhook_signature",
+]

stackshift-1.0.0/stackshift/assets.py

@@ -0,0 +1,390 @@
+from __future__ import annotations
+
+import json
+import hashlib
+from pathlib import Path
+from typing import Any, BinaryIO
+from urllib.parse import quote
+
+
+ASSET_TRANSFORM_PRESETS: list[dict[str, Any]] = [
+    {"id": "web-thumbnail", "name": "web-thumbnail", "category": "responsive-web", "description": "Compact grid thumbnail for libraries and dashboards.", "width": 320, "height": 180, "crop": "fill", "format": "webp", "quality": 78},
+    {"id": "web-card", "name": "web-card", "category": "responsive-web", "description": "Balanced card image for product and content listings.", "width": 640, "height": 360, "crop": "fill", "format": "webp", "quality": 82},
+    {"id": "feature-image", "name": "feature-image", "category": "responsive-web", "description": "Wide content feature image with enough detail for retina screens.", "width": 1200, "height": 675, "crop": "fill", "format": "webp", "quality": 84},
+    {"id": "hero", "name": "hero", "category": "responsive-web", "description": "Large hero image for landing pages and page headers.", "width": 1600, "height": 900, "crop": "fill", "format": "webp", "quality": 84},
+    {"id": "full-width-banner", "name": "full-width-banner", "category": "responsive-web", "description": "Extra-wide banner for app shells and marketing sections.", "width": 1920, "height": 720, "crop": "fill", "format": "webp", "quality": 82},
+    {"id": "open-graph", "name": "open-graph", "category": "social", "description": "Share preview image for Open Graph cards.", "width": 1200, "height": 630, "crop": "fill", "format": "jpeg", "quality": 85},
+    {"id": "square-post", "name": "square-post", "category": "social", "description": "Square image for social feeds.", "width": 1080, "height": 1080, "crop": "fill", "format": "webp", "quality": 84},
+    {"id": "story", "name": "story", "category": "social", "description": "Vertical story format for mobile social placements.", "width": 1080, "height": 1920, "crop": "fill", "format": "webp", "quality": 82},
+    {"id": "x-twitter-card", "name": "x-twitter-card", "category": "social", "description": "Landscape card optimized for X and Twitter previews.", "width": 1200, "height": 675, "crop": "fill", "format": "jpeg", "quality": 84},
+    {"id": "linkedin-share", "name": "linkedin-share", "category": "social", "description": "LinkedIn share preview dimensions.", "width": 1200, "height": 627, "crop": "fill", "format": "jpeg", "quality": 84},
+    {"id": "product-square", "name": "product-square", "category": "product", "description": "Square product image with clean containment.", "width": 1024, "height": 1024, "crop": "fit", "format": "webp", "quality": 86},
+    {"id": "product-card", "name": "product-card", "category": "product", "description": "Product listing image for commerce grids.", "width": 640, "height": 640, "crop": "fit", "format": "webp", "quality": 84},
+    {"id": "product-zoom", "name": "product-zoom", "category": "product", "description": "High-detail product image for zoom interactions.", "width": 2000, "height": 2000, "crop": "fit", "format": "jpeg", "quality": 90},
+    {"id": "gallery-thumb", "name": "gallery-thumb", "category": "product", "description": "Compact gallery thumbnail for product detail pages.", "width": 400, "height": 400, "crop": "fill", "format": "webp", "quality": 82},
+    {"id": "avatar-small", "name": "avatar-small", "category": "avatar-profile", "description": "Small circular avatar source for dense UI.", "width": 128, "height": 128, "crop": "fill", "format": "webp", "quality": 82},
+    {"id": "avatar-retina", "name": "avatar-retina", "category": "avatar-profile", "description": "Retina avatar source for account and profile UI.", "width": 256, "height": 256, "crop": "fill", "format": "webp", "quality": 84},
+    {"id": "profile-cover", "name": "profile-cover", "category": "avatar-profile", "description": "Wide profile cover image.", "width": 1500, "height": 500, "crop": "fill", "format": "webp", "quality": 82},
+    {"id": "webp-auto", "name": "webp-auto", "category": "performance", "description": "Auto-sized WebP delivery with browser-friendly compression.", "width": 1280, "crop": "fit", "format": "webp", "quality": 78},
+    {"id": "avif-compressed", "name": "avif-compressed", "category": "performance", "description": "Highly compressed AVIF for modern browsers.", "width": 1280, "crop": "fit", "format": "avif", "quality": 62},
+    {"id": "lqip", "name": "lqip", "category": "performance", "description": "Tiny low-quality placeholder for progressive image loading.", "width": 48, "crop": "fit", "format": "jpeg", "quality": 35},
+    {"id": "blur-placeholder", "name": "blur-placeholder", "category": "performance", "description": "Small placeholder candidate for blurred loading states.", "width": 32, "height": 32, "crop": "fill", "format": "jpeg", "quality": 30},
+    {"id": "email-safe-600", "name": "email-safe-600", "category": "email-docs", "description": "Email-safe content image with conservative width.", "width": 600, "crop": "fit", "format": "jpeg", "quality": 82},
+    {"id": "markdown-image", "name": "markdown-image", "category": "email-docs", "description": "Documentation image that fits most reading columns.", "width": 800, "crop": "fit", "format": "webp", "quality": 82},
+    {"id": "docs-screenshot", "name": "docs-screenshot", "category": "email-docs", "description": "Crisp screenshot size for guides and changelogs.", "width": 1440, "height": 900, "crop": "fit", "format": "webp", "quality": 84},
+]
+
+
+def get_asset_transform_preset(name: str) -> dict[str, Any] | None:
+    return next((preset for preset in ASSET_TRANSFORM_PRESETS if preset["name"] == name), None)
+
+
+def asset_transform_options(preset: dict[str, Any]) -> dict[str, Any]:
+    return {key: preset[key] for key in ("width", "height", "crop", "format", "quality") if key in preset}
+
+
+def asset_transform_spec(**options: Any) -> str:
+    return _transform_spec(options)
+
+
+class AssetsClient:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def upload(
+        self,
+        file: str | Path | BinaryIO,
+        *,
+        bucket: str | None = None,
+        key: str | None = None,
+        folder: str | None = None,
+        visibility: str | None = None,
+        cache_control: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return self._multipart("POST", "/assets/upload", file, {
+            "bucket": bucket,
+            "key": key,
+            "folder": folder,
+            "visibility": visibility,
+            "cache_control": cache_control,
+            "metadata": json.dumps(metadata) if metadata else None,
+        })
+
+    def list(self, **params: Any) -> dict[str, Any]:
+        clean = {key: value for key, value in params.items() if value not in (None, "")}
+        return self._client.request("GET", "/assets", params=clean)
+
+    def get(self, asset_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/assets/{asset_id}")
+
+    def delete(self, asset_id: str, revision: int, *, idempotency_key: str | None = None) -> dict[str, Any]:
+        headers = {"If-Match": f'"{revision}"'}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        return self._client.request("DELETE", f"/assets/{asset_id}", headers=headers)
+
+    def replace(
+        self,
+        asset_id: str,
+        revision: int,
+        file: str | Path | BinaryIO,
+        *,
+        cache_control: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return self._multipart("PUT", f"/assets/{asset_id}/replace", file, {
+            "cache_control": cache_control,
+            "metadata": json.dumps(metadata) if metadata else None,
+        }, headers={"If-Match": f'"{revision}"'})
+
+    def signed_url(
+        self,
+        asset_id: str,
+        *,
+        expires_in: str = "10m",
+        max_downloads: int | None = None,
+    ) -> dict[str, Any]:
+        return self._client.request("POST", f"/assets/{asset_id}/signed-url", json={
+            "expires_in": expires_in,
+            "max_downloads": max_downloads,
+        })
+
+    def signed_upload_url(self, **payload: Any) -> dict[str, Any]:
+        return self.create_upload_session(**payload)
+
+    def create_upload_session(self, **payload: Any) -> dict[str, Any]:
+        idempotency_key = payload.pop("idempotency_key", None)
+        clean = {key: value for key, value in payload.items() if value not in (None, "")}
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self._client.request("POST", "/assets/upload-sessions", json=clean, headers=headers)
+
+    def create_chunked_upload_session(self, **payload: Any) -> dict[str, Any]:
+        return self.create_upload_session(mode="chunked", **payload)
+
+    def upload_chunk(
+        self,
+        upload_url_or_token: str,
+        part_number: int,
+        chunk: bytes | BinaryIO,
+    ) -> dict[str, Any]:
+        target = upload_url_or_token.rstrip("/")
+        if not target.startswith("http"):
+            origin = self._client.base_url.removesuffix("/api/v1")
+            target = f"{origin}/uploads/{quote(upload_url_or_token)}"
+
+        raw = chunk if isinstance(chunk, bytes) else chunk.read()
+        response = self._client.session.put(
+            f"{target}/parts/{part_number}",
+            data=raw,
+            headers={"User-Agent": "StackShift-Python/0.1", "X-Content-SHA256": hashlib.sha256(raw).hexdigest()},
+        )
+        payload = response.json() if response.content else None
+        if response.status_code < 200 or response.status_code >= 300:
+            message = payload.get("message") if isinstance(payload, dict) else None
+            raise RuntimeError(message or f"StackShift upload failed with {response.status_code}")
+        return payload["data"] if isinstance(payload, dict) and "data" in payload else payload
+
+    def resume_upload_session(self, session_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/assets/upload-sessions/{session_id}")
+
+    def complete_upload_session(self, session_id: str) -> dict[str, Any]:
+        return self._client.request("POST", f"/assets/upload-sessions/{session_id}/complete")
+
+    def cancel_upload_session(self, session_id: str) -> dict[str, Any]:
+        return self._client.request("DELETE", f"/assets/upload-sessions/{session_id}")
+
+    def list_buckets(self) -> dict[str, Any]:
+        return self._client.request("GET", "/assets/buckets")
+
+    def create_bucket(self, **payload: Any) -> dict[str, Any]:
+        return self._client.request("POST", "/assets/buckets", json=payload)
+
+    def update_bucket(self, bucket_id: str, revision: int, **payload: Any) -> dict[str, Any]:
+        return self._client.request("PUT", f"/assets/buckets/{bucket_id}", json=payload, headers={"If-Match": f'"{revision}"'})
+
+    def delete_bucket(self, bucket_id: str, revision: int) -> dict[str, Any]:
+        return self._client.request("DELETE", f"/assets/buckets/{bucket_id}", headers={"If-Match": f'"{revision}"'})
+
+    def set_tags(self, asset_id: str, revision: int, tags: list[str]) -> dict[str, Any]:
+        return self._client.request("PUT", f"/assets/{asset_id}/tags", json={"tags": tags}, headers={"If-Match": f'"{revision}"'})
+
+    def patch_metadata(self, asset_id: str, revision: int, metadata: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request("PATCH", f"/assets/{asset_id}/metadata", json={"metadata": metadata}, headers={"If-Match": f'"{revision}"'})
+
+    def patch(self, asset_id: str, revision: int, **payload: Any) -> dict[str, Any]:
+        return self._client.request("PATCH", f"/assets/{asset_id}", json=payload, headers={"If-Match": f'"{revision}"'})
+
+    def url(self, asset_id: str, **options: Any) -> str:
+        spec = _transform_spec(options)
+        return f"{self._client.cdn_base_url}/assets/{quote(asset_id)}/tr/{quote(spec)}"
+
+    def named_url(self, asset_id: str, name: str) -> str:
+        return f"{self._client.cdn_base_url}/t/{quote(name)}/assets/{quote(asset_id)}"
+
+    def version_url(self, asset_id: str, version_id: str, token: str | None = None) -> str:
+        prefix = "/private/assets" if token else "/assets"
+        result = f"{self._client.cdn_base_url}{prefix}/{quote(asset_id)}/versions/{quote(version_id)}"
+        return f"{result}?token={quote(token)}" if token else result
+
+    def branch_url(self, asset_id: str, branch: str, token: str | None = None) -> str:
+        prefix = "/private/assets" if token else "/assets"
+        result = f"{self._client.cdn_base_url}{prefix}/{quote(asset_id)}/branches/{quote(branch)}"
+        return f"{result}?token={quote(token)}" if token else result
+
+    def video_url(self, asset_id: str, kind: str, profile: str = "default", token: str | None = None) -> str:
+        prefix = "/private/assets" if token else "/assets"
+        result = f"{self._client.cdn_base_url}{prefix}/{quote(asset_id)}/video/{quote(kind)}/{quote(profile)}"
+        return f"{result}?token={quote(token)}" if token else result
+
+    def ai(self, asset_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/assets/{asset_id}/ai")
+
+    def request_ai_analyze(self, asset_id: str, *, idempotency_key: str | None = None) -> dict[str, Any]:
+        return self._request_ai_job(f"/assets/{asset_id}/ai/analyze", idempotency_key)
+
+    def request_moderation(self, asset_id: str, *, idempotency_key: str | None = None) -> dict[str, Any]:
+        return self._request_ai_job(f"/assets/{asset_id}/moderation", idempotency_key)
+
+    def transcript(self, asset_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/assets/{asset_id}/transcript")
+
+    def request_transcript(self, asset_id: str, *, idempotency_key: str | None = None) -> dict[str, Any]:
+        return self._request_ai_job(f"/assets/{asset_id}/transcript", idempotency_key)
+
+    def request_smart_crop(self, asset_id: str, *, idempotency_key: str | None = None) -> dict[str, Any]:
+        return self._request_ai_job(f"/assets/{asset_id}/smart-crop", idempotency_key)
+
+    def request_background_removal(self, asset_id: str, *, idempotency_key: str | None = None) -> dict[str, Any]:
+        return self._request_ai_job(f"/assets/{asset_id}/background-remove", idempotency_key)
+
+    def _request_ai_job(self, path: str, idempotency_key: str | None) -> dict[str, Any]:
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self._client.request("POST", path, headers=headers)
+
+    def versions(self, asset_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/assets/{asset_id}/versions")
+
+    def create_branch(
+        self,
+        asset_id: str,
+        name: str,
+        from_version_id: str | None = None,
+    ) -> dict[str, Any]:
+        payload = {"name": name, "from_version_id": from_version_id}
+        clean = {key: value for key, value in payload.items() if value not in (None, "")}
+        return self._client.request("POST", f"/assets/{asset_id}/branches", json=clean)
+
+    def restore_version(self, asset_id: str, version_id: str) -> dict[str, Any]:
+        return self._client.request("POST", f"/assets/{asset_id}/versions/{version_id}/restore")
+
+    def promote_branch(self, asset_id: str, branch: str) -> dict[str, Any]:
+        return self._client.request("POST", f"/assets/{asset_id}/branches/{quote(branch)}/promote")
+
+    def collections(self) -> dict[str, Any]:
+        return self._client.request("GET", "/assets/collections")
+
+    def create_collection(self, **payload: Any) -> dict[str, Any]:
+        clean = {key: value for key, value in payload.items() if value not in (None, "")}
+        return self._client.request("POST", "/assets/collections", json=clean)
+
+    def update_collection(self, collection_id: str, **payload: Any) -> dict[str, Any]:
+        clean = {key: value for key, value in payload.items() if value not in (None, "")}
+        return self._client.request("PUT", f"/assets/collections/{collection_id}", json=clean)
+
+    def delete_collection(self, collection_id: str) -> dict[str, Any]:
+        return self._client.request("DELETE", f"/assets/collections/{collection_id}")
+
+    def saved_searches(self) -> dict[str, Any]:
+        return self._client.request("GET", "/assets/saved-searches")
+
+    def save_search(self, **payload: Any) -> dict[str, Any]:
+        clean = {key: value for key, value in payload.items() if value not in (None, "")}
+        return self._client.request("POST", "/assets/saved-searches", json=clean)
+
+    def update_saved_search(self, search_id: str, **payload: Any) -> dict[str, Any]:
+        clean = {key: value for key, value in payload.items() if value not in (None, "")}
+        return self._client.request("PUT", f"/assets/saved-searches/{search_id}", json=clean)
+
+    def delete_saved_search(self, search_id: str) -> dict[str, Any]:
+        return self._client.request("DELETE", f"/assets/saved-searches/{search_id}")
+
+    def get_policy(self) -> dict[str, Any]:
+        return self._client.request("GET", "/assets/policy")
+
+    def update_policy(self, **payload: Any) -> dict[str, Any]:
+        clean = {key: value for key, value in payload.items() if value not in (None, "")}
+        return self._client.request("PUT", "/assets/policy", json=clean)
+
+    def create_transformation(self, name: str, **options: Any) -> dict[str, Any]:
+        payload = {"name": name, **options}
+        clean = {key: value for key, value in payload.items() if value not in (None, "")}
+        return self._client.request("POST", "/assets/transformations", json=clean)
+
+    def list_transformations(self) -> dict[str, Any]:
+        return self._client.request("GET", "/assets/transformations")
+
+    def delete_transformation(self, name: str) -> dict[str, Any]:
+        return self._client.request("DELETE", f"/assets/transformations/{quote(name)}")
+
+    def signed_transform_url(self, asset_id: str, **options: Any) -> dict[str, Any]:
+        clean = {key: value for key, value in options.items() if value not in (None, "")}
+        return self._client.request("POST", f"/assets/{asset_id}/transform-url", json=clean)
+
+    def get_ai_config(self) -> dict[str, Any]:
+        return self._client.request("GET", "/assets/ai/config")
+
+    def update_ai_config(self, revision: int, *, enabled_actions: list[str], monthly_spend_cap_micros: int) -> dict[str, Any]:
+        return self._client.request("PUT", "/assets/ai/config", headers={"If-Match": f'"{revision}"'}, json={
+            "enabled_actions": enabled_actions,
+            "monthly_spend_cap_micros": monthly_spend_cap_micros,
+        })
+
+    def job(self, job_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/assets/jobs/{quote(job_id)}")
+
+    def cancel_job(self, job_id: str) -> dict[str, Any]:
+        return self._client.request("POST", f"/assets/jobs/{quote(job_id)}/cancel")
+
+    def create_lifecycle_rule(self, **payload: Any) -> dict[str, Any]:
+        return self._client.request("POST", "/assets/lifecycle-rules", json=payload)
+
+    def list_lifecycle_rules(self) -> dict[str, Any]:
+        return self._client.request("GET", "/assets/lifecycle-rules")
+
+    def delete_lifecycle_rule(self, rule_id: str) -> dict[str, Any]:
+        return self._client.request("DELETE", f"/assets/lifecycle-rules/{quote(rule_id)}")
+
+    def create_domain(self, domain: str) -> dict[str, Any]:
+        return self._client.request("POST", "/assets/domains", json={"domain": domain})
+
+    def list_domains(self) -> dict[str, Any]:
+        return self._client.request("GET", "/assets/domains")
+
+    def verify_domain(self, domain_id: str) -> dict[str, Any]:
+        return self._client.request("POST", f"/assets/domains/{quote(domain_id)}/verify")
+
+    def delete_domain(self, domain_id: str) -> dict[str, Any]:
+        return self._client.request("DELETE", f"/assets/domains/{quote(domain_id)}")
+
+    def analytics(self) -> dict[str, Any]:
+        return self._client.request("GET", "/assets/analytics")
+
+    def usage_summary(self) -> dict[str, Any]:
+        return self._client.request("GET", "/assets/summary")
+
+    def events(self, limit: int = 50) -> dict[str, Any]:
+        return self._client.request("GET", "/assets/events", params={"limit": limit})
+
+    def create_webhook(self, url: str, event_types: list[str] | None = None) -> dict[str, Any]:
+        return self._client.request("POST", "/assets/webhooks", json={"url": url, "event_types": event_types or ["asset.*"]})
+
+    def list_webhooks(self) -> dict[str, Any]:
+        return self._client.request("GET", "/assets/webhooks")
+
+    def delete_webhook(self, webhook_id: str) -> dict[str, Any]:
+        return self._client.request("DELETE", f"/assets/webhooks/{quote(webhook_id)}")
+
+    def list_webhook_deliveries(self, webhook_id: str, limit: int = 50) -> dict[str, Any]:
+        return self._client.request("GET", f"/assets/webhooks/{quote(webhook_id)}/deliveries", params={"limit": limit})
+
+    def retry_webhook_delivery(self, delivery_id: str) -> dict[str, Any]:
+        return self._client.request("POST", f"/assets/webhook-deliveries/{quote(delivery_id)}/retry")
+
+    def purge(self, asset_id: str) -> dict[str, Any]:
+        return self._client.request("POST", f"/assets/{quote(asset_id)}/purge")
+
+    def bulk(self, *, action: str, items: list[dict[str, Any]], idempotency_key: str | None = None, **payload: Any) -> dict[str, Any]:
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self._client.request("POST", "/assets/bulk", json={"action": action, "items": items, **payload}, headers=headers)
+
+    def _multipart(self, method: str, suffix: str, file: str | Path | BinaryIO, fields: dict[str, Any], headers: dict[str, str] | None = None) -> dict[str, Any]:
+        should_close = False
+        if isinstance(file, (str, Path)):
+            handle = Path(file).open("rb")
+            filename = Path(file).name
+            should_close = True
+        else:
+            handle = file
+            filename = getattr(file, "name", "asset")
+
+        try:
+            data = {key: value for key, value in fields.items() if value not in (None, "")}
+            return self._client.request(method, suffix, data=data, files={"file": (filename, handle)}, headers=headers)
+        finally:
+            if should_close:
+                handle.close()
+
+
+def _transform_spec(options: dict[str, Any]) -> str:
+    parts: list[str] = []
+    if options.get("width"):
+        parts.append(f"w_{options['width']}")
+    if options.get("height"):
+        parts.append(f"h_{options['height']}")
+    parts.append(f"c_{options.get('crop') or 'fit'}")
+    parts.append(f"f_{options.get('format') or 'auto'}")
+    parts.append(f"q_{options.get('quality') or 'auto'}")
+    parts.append(f"g_{options.get('gravity') or 'centre'}")
+    parts.append(f"a_{options.get('animation') or 'first'}")
+    return ",".join(parts)