adcontextprotocol
diff --git a/‎examples/README.md‎
Lines changed: 144 additions & 0 deletions b/‎examples/README.md‎
Lines changed: 144 additions & 0 deletions
diff --git a/‎examples/fetch_preview_urls.py‎
Lines changed: 89 additions & 0 deletions b/‎examples/fetch_preview_urls.py‎
Lines changed: 89 additions & 0 deletions
diff --git a/‎examples/generate_mock_previews.py‎
Lines changed: 64 additions & 0 deletions b/‎examples/generate_mock_previews.py‎
Lines changed: 64 additions & 0 deletions
diff --git a/‎examples/preview_urls.json‎
Lines changed: 23 additions & 0 deletions b/‎examples/preview_urls.json‎
Lines changed: 23 additions & 0 deletions
@@ -0,0 +1,144 @@
+# ADCP Python Client Examples
+
+This directory contains examples demonstrating how to use the ADCP Python client's preview URL generation feature.
+
+## Preview URL Generation Demo
+
+This demo shows how to fetch creative format previews from the ADCP creative agent and display them in a web browser using the `<rendered-creative>` web component.
+
+### Quick Start
+
+1. **Install the package** (if not already installed):
+   ```bash
+   pip install -e .
+   ```
+
+2. **Fetch preview URLs from the creative agent**:
+   ```bash
+   python examples/fetch_previews.py
+   ```
+
+   This will:
+   - Connect to the reference creative agent at `https://creative.adcontextprotocol.org`
+   - Call `list_creative_formats()` with `fetch_previews=True`
+   - Generate preview URLs for available formats
+   - Save the results to `examples/preview_urls.json`
+
+3. **Start a local web server** (required for the web component to work):
+   ```bash
+   cd /path/to/adcp-client-python
+   python -m http.server 8000
+   ```
+
+4. **Open the demo in your browser**:
+   ```
+   http://localhost:8000/examples/web_component_demo.html
+   ```
+
+### What You'll See
+
+The demo page displays a grid of creative format previews, each showing:
+- Format name
+- Format ID
+- Live preview rendered in the `<rendered-creative>` web component
+
+Features demonstrated:
+- **Shadow DOM isolation** - No CSS conflicts between previews
+- **Lazy loading** - Previews load only when visible
+- **Responsive grid** - Adapts to different screen sizes
+- **Interactive previews** - Full creative rendering with animations
+
+### Files
+
+- **`fetch_previews.py`** - Python script to fetch preview URLs from the creative agent
+- **`web_component_demo.html`** - HTML page demonstrating the `<rendered-creative>` web component
+- **`preview_urls.json`** - Generated file containing preview URLs (created by fetch script)
+
+### How It Works
+
+The Python script uses the new `fetch_previews` parameter:
+
+```python
+from adcp import ADCPClient
+from adcp.types import AgentConfig, Protocol
+from adcp.types.generated import ListCreativeFormatsRequest
+
+creative_agent = ADCPClient(
+    AgentConfig(
+        id="creative_agent",
+        agent_uri="https://creative.adcontextprotocol.org",
+        protocol=Protocol.MCP,
+    )
+)
+
+# Fetch formats with preview URLs
+result = await creative_agent.list_creative_formats(
+    ListCreativeFormatsRequest(),
+    fetch_previews=True  # ← New parameter!
+)
+
+# Access preview data
+formats_with_previews = result.metadata["formats_with_previews"]
+for fmt in formats_with_previews:
+    preview_data = fmt["preview_data"]
+    print(f"Preview URL: {preview_data['preview_url']}")
+    print(f"Expires: {preview_data['expires_at']}")
+```
+
+The HTML page then uses the official ADCP web component to render the previews:
+
+```html
+<!-- Include the web component -->
+<script src="https://creative.adcontextprotocol.org/static/rendered-creative.js"></script>
+
+<!-- Render previews -->
+<rendered-creative
+    src="{{preview_url}}"
+    width="300"
+    height="400"
+    lazy="true">
+</rendered-creative>
+```
+
+### Troubleshooting
+
+**"Preview URLs file not found" error:**
+- Run `python examples/fetch_previews.py` first
+
+**Web component not loading:**
+- Make sure you're using a web server (not `file://` URLs)
+- Check that you have internet access (web component loads from CDN)
+
+**No previews showing:**
+- Check browser console for errors
+- Verify the creative agent is accessible: `https://creative.adcontextprotocol.org`
+
+### Using with Products
+
+You can also fetch preview URLs for products:
+
+```python
+from adcp.types.generated import GetProductsRequest
+
+# Setup publisher and creative agents
+publisher_agent = ADCPClient(publisher_config)
+creative_agent = ADCPClient(creative_config)
+
+# Get products with preview URLs
+result = await publisher_agent.get_products(
+    GetProductsRequest(brief="video campaign"),
+    fetch_previews=True,
+    creative_agent_client=creative_agent
+)
+
+# Access product previews
+products_with_previews = result.metadata["products_with_previews"]
+for product in products_with_previews:
+    print(f"Product: {product['name']}")
+    for format_id, preview_data in product["format_previews"].items():
+        print(f"  Format {format_id}: {preview_data['preview_url']}")
+```
+
+## More Examples
+
+For more examples, see the [documentation](https://docs.adcontextprotocol.org) and [integration tests](../tests/integration/).
@@ -0,0 +1,89 @@
+"""
+Example script to fetch preview URLs from the ADCP creative agent.
+
+This demonstrates the new preview URL generation feature by:
+1. Connecting to the reference creative agent
+2. Listing available formats
+3. Generating preview URLs for each format
+4. Saving the results to use in the web component demo
+"""
+
+import asyncio
+import json
+from pathlib import Path
+
+from adcp import ADCPClient
+from adcp.types import AgentConfig, Protocol
+from adcp.types.generated import ListCreativeFormatsRequest
+
+
+async def main():
+    """Fetch preview URLs from the creative agent."""
+
+    # Connect to the reference creative agent
+    creative_agent = ADCPClient(
+        AgentConfig(
+            id="creative_agent",
+            agent_uri="https://creative.adcontextprotocol.org",
+            protocol=Protocol.MCP,
+        )
+    )
+
+    print("Fetching creative formats with preview URLs...")
+    print("=" * 60)
+
+    try:
+        # List formats with preview URL generation
+        result = await creative_agent.list_creative_formats(
+            ListCreativeFormatsRequest(), fetch_previews=True
+        )
+
+        if not result.success:
+            print(f"❌ Failed to fetch formats: {result.error}")
+            return
+
+        # Get formats with previews from metadata
+        formats_with_previews = result.metadata.get("formats_with_previews", [])
+
+        print(f"\n✅ Successfully fetched {len(formats_with_previews)} formats with previews\n")
+
+        # Display preview URLs
+        preview_data = []
+        for fmt in formats_with_previews[:5]:  # Show first 5
+            format_id = fmt.get("format_id")
+            name = fmt.get("name", "Unknown")
+            preview = fmt.get("preview_data", {})
+            preview_url = preview.get("preview_url")
+
+            if preview_url:
+                print(f"📋 {name}")
+                print(f"   Format ID: {format_id}")
+                print(f"   Preview URL: {preview_url}")
+                print(f"   Expires: {preview.get('expires_at', 'N/A')}")
+                print()
+
+                preview_data.append({
+                    "format_id": format_id,
+                    "name": name,
+                    "preview_url": preview_url,
+                    "width": 300,
+                    "height": 400,
+                })
+
+        # Save to JSON for the web component demo
+        output_file = Path(__file__).parent / "preview_urls.json"
+        with open(output_file, "w") as f:
+            json.dump(preview_data, f, indent=2)
+
+        print(f"💾 Saved preview URLs to: {output_file}")
+        print(f"\n🌐 Open examples/web_component_demo.html in a browser to see the previews!")
+
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        raise
+    finally:
+        await creative_agent.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,64 @@
+"""
+Generate mock preview data for demonstration purposes.
+
+Note: This uses mock data because the reference creative agent at
+https://creative.adcontextprotocol.org doesn't currently return
+structured format data via MCP (it returns a text message instead).
+
+This demonstrates what the preview URL feature would look like
+when connected to a properly implemented ADCP creative agent.
+"""
+
+import json
+from pathlib import Path
+
+
+def main():
+    """Generate mock preview URLs."""
+
+    # Mock preview data that demonstrates the feature
+    mock_previews = [
+        {
+            "format_id": "display_300x250",
+            "name": "Display 300x250",
+            "preview_url": "https://creative.adcontextprotocol.org/preview/sample-banner/desktop.html",
+            "width": 300,
+            "height": 250,
+        },
+        {
+            "format_id": "display_728x90",
+            "name": "Display 728x90 Leaderboard",
+            "preview_url": "https://creative.adcontextprotocol.org/preview/sample-leaderboard/desktop.html",
+            "width": 728,
+            "height": 90,
+        },
+        {
+            "format_id": "display_160x600",
+            "name": "Display 160x600 Skyscraper",
+            "preview_url": "https://creative.adcontextprotocol.org/preview/sample-skyscraper/desktop.html",
+            "width": 160,
+            "height": 600,
+        },
+    ]
+
+    # Save to JSON
+    output_file = Path(__file__).parent / "preview_urls.json"
+    with open(output_file, "w") as f:
+        json.dump(mock_previews, f, indent=2)
+
+    print("✅ Generated mock preview URLs")
+    print(f"💾 Saved to: {output_file}")
+    print()
+    print("Mock previews:")
+    for preview in mock_previews:
+        print(f"  - {preview['name']}: {preview['preview_url']}")
+    print()
+    print("🌐 Open examples/web_component_demo.html in a browser to see them!")
+    print()
+    print("Note: These are mock URLs for demonstration. In a real implementation,")
+    print("the preview URLs would be generated by calling preview_creative on the")
+    print("creative agent for each format.")
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,23 @@
+[
+  {
+    "format_id": "display_300x250",
+    "name": "Display 300x250",
+    "preview_url": "https://creative.adcontextprotocol.org/preview/sample-banner/desktop.html",
+    "width": 300,
+    "height": 250
+  },
+  {
+    "format_id": "display_728x90",
+    "name": "Display 728x90 Leaderboard",
+    "preview_url": "https://creative.adcontextprotocol.org/preview/sample-leaderboard/desktop.html",
+    "width": 728,
+    "height": 90
+  },
+  {
+    "format_id": "display_160x600",
+    "name": "Display 160x600 Skyscraper",
+    "preview_url": "https://creative.adcontextprotocol.org/preview/sample-skyscraper/desktop.html",
+    "width": 160,
+    "height": 600
+  }
+]