pdfbridge-python 1.0.0__tar.gz

pdfbridge_python-1.0.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: pdfbridge-python
+Version: 1.0.0
+Summary: The official Python SDK for the PDFBridge API. Generate pixel-perfect PDFs from HTML/URLs.
+Project-URL: Homepage, https://pdfbridge.xyz
+Project-URL: Bug Tracker, https://github.com/techhspyder/pdfbridge-python/issues
+Author-email: TechhSpyder <hello@techhspyder.com>
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: requests>=2.25.1
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: responses>=0.23.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="https://assets.pdfbridge.xyz/logo.svg" alt="PDFBridge Logo" width="200"/>
+  <h1>pdfbridge-python</h1>
+  <p>The official Python SDK for the <a href="https://pdfbridge.xyz">PDFBridge API</a>. Generate pixel-perfect PDFs from HTML or URLs.</p>
+</div>
+
+[![PyPI version](https://badge.fury.io/py/pdfbridge-python.svg)](https://badge.fury.io/py/pdfbridge-python)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python Support](https://img.shields.io/pypi/pyversions/pdfbridge-python.svg)](https://pypi.org/project/pdfbridge-python/)
+
+## Features
+
+- **Typed Inputs & Outputs**: Fully powered by Pydantic V2 for strict runtime validation and autocomplete.
+- **Convenient Sync Methods**: Out-of-the-box `generate_and_wait` blocking wrapper so you don't have to write your own pollers.
+- **Ghost Mode Native**: Fetch raw PDF bytes directly into memory. No intermediate storage or URLs.
+- **Bulk Conversions**: Convert up to 1,000 documents simultaneously.
+
+---
+
+## Installation
+
+```bash
+pip install pdfbridge-python
+```
+
+## Quick Start
+
+```python
+import os
+from pdfbridge import PDFBridge
+
+# Initialize with your secret API key
+# Can also be picked up automatically via the PDFBRIDGE_API_KEY environment variable.
+client = PDFBridge(api_key="pk_live_your_key_here")
+
+# Generate and wait for completion (blocks execution until PDF is ready)
+status = client.generate_and_wait(
+    url="https://github.com",
+    filename="github_page.pdf",
+    options={
+        "format": "A4",
+        "printBackground": True
+    }
+)
+
+print(f"Success! Download PDF from: {status.pdfUrl}")
+```
+
+## Advanced Usage
+
+### 👻 Ghost Mode (Memory-Native)
+
+Ghost Mode returns the direct `bytes` of the generated PDF without saving it to Cloud Storage. This is perfect for securely piping documents to your own S3 bucket or streaming directly to users.
+
+```python
+# Returns raw bytes natively
+pdf_bytes = client.generate(
+    html="<h1>Highly Confidential Financial Data</h1>",
+    ghostMode=True,
+    options={
+        "format": "Letter",
+        "margin": "1in"
+    }
+)
+
+with open("secure_report.pdf", "wb") as f:
+    f.write(pdf_bytes)
+```
+
+### 🚀 Bulk Generation
+
+Queue up to 1,000 PDF generation jobs natively in a single API call.
+
+```python
+bulk_job = client.generate_bulk(
+    webhookUrl="https://api.yourdomain.com/webhooks/pdfbridge",
+    jobs=[
+        {"url": "https://example.com/invoice/123", "filename": "INV-123.pdf"},
+        {"url": "https://example.com/invoice/124", "filename": "INV-124.pdf"},
+        {"url": "https://example.com/invoice/125", "filename": "INV-125.pdf"}
+    ]
+)
+
+print(f"Queued {len(bulk_job.jobs)} items.")
+```
+
+### 🧠 Templates & Variables
+
+Pass dynamic data into your saved HTML templates.
+
+```python
+client.generate_and_wait(
+    templateId="tmpl_987654321",
+    variables={
+        "customer_name": "Jane Doe",
+        "total_amount": "$45.00"
+    }
+)
+```
+
+## Error Handling
+
+The SDK raises `PDFBridgeError` on any HTTP failures, authentication issues, or data malformations.
+
+```python
+from pdfbridge import PDFBridgeError
+
+try:
+    client.generate(url="invalid-url")
+except PDFBridgeError as e:
+    print(f"API Failed with status {e.status_code}: {str(e)}")
+```

pdfbridge_python-1.0.0/README.md

@@ -0,0 +1,112 @@
+<div align="center">
+  <img src="https://assets.pdfbridge.xyz/logo.svg" alt="PDFBridge Logo" width="200"/>
+  <h1>pdfbridge-python</h1>
+  <p>The official Python SDK for the <a href="https://pdfbridge.xyz">PDFBridge API</a>. Generate pixel-perfect PDFs from HTML or URLs.</p>
+</div>
+
+[![PyPI version](https://badge.fury.io/py/pdfbridge-python.svg)](https://badge.fury.io/py/pdfbridge-python)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python Support](https://img.shields.io/pypi/pyversions/pdfbridge-python.svg)](https://pypi.org/project/pdfbridge-python/)
+
+## Features
+
+- **Typed Inputs & Outputs**: Fully powered by Pydantic V2 for strict runtime validation and autocomplete.
+- **Convenient Sync Methods**: Out-of-the-box `generate_and_wait` blocking wrapper so you don't have to write your own pollers.
+- **Ghost Mode Native**: Fetch raw PDF bytes directly into memory. No intermediate storage or URLs.
+- **Bulk Conversions**: Convert up to 1,000 documents simultaneously.
+
+---
+
+## Installation
+
+```bash
+pip install pdfbridge-python
+```
+
+## Quick Start
+
+```python
+import os
+from pdfbridge import PDFBridge
+
+# Initialize with your secret API key
+# Can also be picked up automatically via the PDFBRIDGE_API_KEY environment variable.
+client = PDFBridge(api_key="pk_live_your_key_here")
+
+# Generate and wait for completion (blocks execution until PDF is ready)
+status = client.generate_and_wait(
+    url="https://github.com",
+    filename="github_page.pdf",
+    options={
+        "format": "A4",
+        "printBackground": True
+    }
+)
+
+print(f"Success! Download PDF from: {status.pdfUrl}")
+```
+
+## Advanced Usage
+
+### 👻 Ghost Mode (Memory-Native)
+
+Ghost Mode returns the direct `bytes` of the generated PDF without saving it to Cloud Storage. This is perfect for securely piping documents to your own S3 bucket or streaming directly to users.
+
+```python
+# Returns raw bytes natively
+pdf_bytes = client.generate(
+    html="<h1>Highly Confidential Financial Data</h1>",
+    ghostMode=True,
+    options={
+        "format": "Letter",
+        "margin": "1in"
+    }
+)
+
+with open("secure_report.pdf", "wb") as f:
+    f.write(pdf_bytes)
+```
+
+### 🚀 Bulk Generation
+
+Queue up to 1,000 PDF generation jobs natively in a single API call.
+
+```python
+bulk_job = client.generate_bulk(
+    webhookUrl="https://api.yourdomain.com/webhooks/pdfbridge",
+    jobs=[
+        {"url": "https://example.com/invoice/123", "filename": "INV-123.pdf"},
+        {"url": "https://example.com/invoice/124", "filename": "INV-124.pdf"},
+        {"url": "https://example.com/invoice/125", "filename": "INV-125.pdf"}
+    ]
+)
+
+print(f"Queued {len(bulk_job.jobs)} items.")
+```
+
+### 🧠 Templates & Variables
+
+Pass dynamic data into your saved HTML templates.
+
+```python
+client.generate_and_wait(
+    templateId="tmpl_987654321",
+    variables={
+        "customer_name": "Jane Doe",
+        "total_amount": "$45.00"
+    }
+)
+```
+
+## Error Handling
+
+The SDK raises `PDFBridgeError` on any HTTP failures, authentication issues, or data malformations.
+
+```python
+from pdfbridge import PDFBridgeError
+
+try:
+    client.generate(url="invalid-url")
+except PDFBridgeError as e:
+    print(f"API Failed with status {e.status_code}: {str(e)}")
+```

pdfbridge_python-1.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pdfbridge-python"
+version = "1.0.0"
+description = "The official Python SDK for the PDFBridge API. Generate pixel-perfect PDFs from HTML/URLs."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [
+  { name = "TechhSpyder", email = "hello@techhspyder.com" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "requests>=2.25.1",
+    "pydantic>=2.0.0",
+]
+
+[project.urls]
+"Homepage" = "https://pdfbridge.xyz"
+"Bug Tracker" = "https://github.com/techhspyder/pdfbridge-python/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "responses>=0.23.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pdfbridge"]
+
+[tool.pytest.ini_options]
+addopts = "-v --cov=pdfbridge"
+testpaths = ["tests"]

pdfbridge_python-1.0.0/src/pdfbridge/__init__.py

@@ -0,0 +1,20 @@
+from .client import PDFBridge, PDFBridgeError
+from .models import (
+    ConvertRequest,
+    BulkConvertRequest,
+    ConvertResponse,
+    BulkConvertResponse,
+    JobStatusResponse,
+    PdfOptions,
+)
+
+__all__ = [
+    "PDFBridge",
+    "PDFBridgeError",
+    "ConvertRequest",
+    "BulkConvertRequest",
+    "ConvertResponse",
+    "BulkConvertResponse",
+    "JobStatusResponse",
+    "PdfOptions",
+]

pdfbridge_python-1.0.0/src/pdfbridge/client.py

@@ -0,0 +1,125 @@
+import os
+import time
+import requests
+from typing import Optional, Union, Dict, Any
+
+from .models import (
+    ConvertRequest,
+    BulkConvertRequest,
+    ConvertResponse,
+    BulkConvertResponse,
+    JobStatusResponse,
+)
+
+
+class PDFBridgeError(Exception):
+    def __init__(self, message: str, status_code: Optional[int] = None, metadata: Optional[Dict[str, Any]] = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.metadata = metadata
+
+
+class PDFBridge:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = "https://api.pdfbridge.xyz/api/v1",
+        max_retries: int = 2,
+    ):
+        self.api_key = api_key or os.environ.get("PDFBRIDGE_API_KEY")
+        if not self.api_key:
+            raise PDFBridgeError(
+                "API Key is required to initialize the PDFBridge Client. Pass it explicitly or set PDFBRIDGE_API_KEY in your environment."
+            )
+
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self.session = requests.Session()
+        self.session.headers.update({
+            "Content-Type": "application/json",
+            "x-api-key": self.api_key,
+            "User-Agent": "pdfbridge-python/1.0.0",
+        })
+
+    def _request(self, method: str, path: str, **kwargs) -> Any:
+        url = f"{self.base_url}{path if path.startswith('/') else '/' + path}"
+        attempt = 0
+
+        while attempt <= self.max_retries:
+            try:
+                response = self.session.request(method, url, **kwargs)
+
+                if response.status_code == 204:
+                    return None
+
+                # Handle binary ghost mode response
+                content_type = response.headers.get("content-type", "")
+                if "application/json" not in content_type and response.ok:
+                    return response.content
+
+                try:
+                    data = response.json()
+                except ValueError:
+                    data = {}
+
+                if not response.ok:
+                    raise PDFBridgeError(
+                        data.get("message") or data.get("error") or f"Request failed with status {response.status_code}",
+                        status_code=response.status_code,
+                        metadata=data,
+                    )
+
+                return data
+
+            except requests.exceptions.RequestException as e:
+                if attempt == self.max_retries:
+                    raise PDFBridgeError(f"Network error: {str(e)}")
+                attempt += 1
+                time.sleep((2 ** attempt) * 0.5)
+
+        raise PDFBridgeError("Unknown network error occurred.")
+
+    def generate(self, **kwargs) -> Union[ConvertResponse, bytes]:
+        """
+        Start a new URL or HTML to PDF conversion job.
+        If ghostMode=True is passed, this immediately returns raw PDF bytes.
+        Otherwise, returns a ConvertResponse map containing the jobId.
+        """
+        payload = ConvertRequest.model_validate(kwargs)
+        res = self._request("POST", "/convert", json=payload.model_dump(exclude_none=True))
+        
+        if payload.ghostMode:
+            return res  # returns bytes directly
+        return ConvertResponse.model_validate(res)
+
+    def generate_and_wait(self, poll_interval_ms: int = 2000, **kwargs) -> JobStatusResponse:
+        """
+        Start a new job and automatically poll the status endpoint until COMPLETED or FAILED.
+        Returns the final JobStatusResponse containing the pdfUrl.
+        """
+        payload = ConvertRequest.model_validate(kwargs)
+        if payload.ghostMode:
+            raise PDFBridgeError("Cannot use generate_and_wait with ghostMode=True. Using ghostMode natively returns the bytes immediately on the standard .generate() method.")
+
+        init_response = self.generate(**kwargs)
+        job_id = init_response.jobId
+
+        while True:
+            time.sleep(poll_interval_ms / 1000.0)
+            status = self.get_job(job_id)
+
+            if status.status == "COMPLETED":
+                return status
+            if status.status == "FAILED":
+                raise PDFBridgeError(f"Job failed: {status.error}", metadata=status.model_dump())
+
+    def generate_bulk(self, **kwargs) -> BulkConvertResponse:
+        """Start a bulk conversion job for up to 1,000 documents at once."""
+        payload = BulkConvertRequest.model_validate(kwargs)
+        res = self._request("POST", "/convert/bulk", json=payload.model_dump(exclude_none=True))
+        return BulkConvertResponse.model_validate(res)
+
+    def get_job(self, job_id: str) -> JobStatusResponse:
+        """Retrieve the status of an existing conversion job."""
+        res = self._request("GET", f"/jobs/{job_id}")
+        return JobStatusResponse.model_validate(res)

pdfbridge_python-1.0.0/src/pdfbridge/models.py

@@ -0,0 +1,76 @@
+from typing import Optional, List, Dict, Any, Union
+from pydantic import BaseModel, Field, HttpUrl, model_validator
+
+
+class PdfOptions(BaseModel):
+    format: Optional[str] = Field(None, description="A4, Letter, Legal, Tabloid, Ledger, A3")
+    landscape: Optional[bool] = None
+    printBackground: Optional[bool] = None
+    scale: Optional[float] = Field(None, ge=0.1, le=2.0)
+    margin: Optional[str] = None
+    marginTop: Optional[str] = None
+    marginBottom: Optional[str] = None
+    marginLeft: Optional[str] = None
+    marginRight: Optional[str] = None
+    displayHeaderFooter: Optional[bool] = None
+    headerTemplate: Optional[str] = None
+    footerTemplate: Optional[str] = None
+    preferCSSPageSize: Optional[bool] = None
+    width: Optional[str] = None
+    height: Optional[str] = None
+    waitDelay: Optional[str] = None
+    userAgent: Optional[str] = None
+    waitForSelector: Optional[str] = None
+    metadata: Optional[Dict[str, str]] = None
+
+
+class ConvertRequest(BaseModel):
+    url: Optional[str] = None
+    html: Optional[str] = None
+    filename: Optional[str] = None
+    webhookUrl: Optional[str] = None
+    ghostMode: Optional[bool] = None
+    tailwind: Optional[bool] = None
+    extractMetadata: Optional[bool] = None
+    templateId: Optional[str] = None
+    variables: Optional[Dict[str, Any]] = None
+    options: Optional[PdfOptions] = None
+
+    @model_validator(mode='after')
+    def check_source_provided(self) -> 'ConvertRequest':
+        if not self.url and not self.html and not self.templateId:
+            raise ValueError("You must provide either 'url', 'html', or 'templateId'")
+        return self
+
+
+class BulkConvertRequest(BaseModel):
+    jobs: List[ConvertRequest] = Field(..., min_length=1, max_length=1000)
+    ghostMode: Optional[bool] = None
+    webhookUrl: Optional[str] = None
+    extractMetadata: Optional[bool] = None
+
+
+class ConvertResponse(BaseModel):
+    message: str
+    jobId: str
+    statusUrl: str
+
+
+class JobItem(BaseModel):
+    jobId: str
+    statusUrl: str
+
+
+class BulkConvertResponse(BaseModel):
+    message: str
+    jobs: List[JobItem]
+
+
+class JobStatusResponse(BaseModel):
+    id: str
+    status: str  # 'PENDING', 'PROCESSING', 'COMPLETED', 'FAILED'
+    pdfUrl: Optional[str] = None
+    error: Optional[str] = None
+    createdAt: str
+    updatedAt: str
+    metadata: Optional[Any] = None

pdfbridge_python-1.0.0/tests/test_sdk.py

@@ -0,0 +1,115 @@
+import json
+import pytest
+import responses
+from pdfbridge import PDFBridge, PDFBridgeError
+from pdfbridge.models import JobStatusResponse, ConvertResponse
+
+API_KEY = "pk_test_123"
+BASE_URL = "https://api.pdfbridge.xyz/api/v1"
+
+@pytest.fixture
+def client():
+    return PDFBridge(api_key=API_KEY)
+
+
+def test_init_without_api_key(monkeypatch):
+    monkeypatch.delenv("PDFBRIDGE_API_KEY", raising=False)
+    with pytest.raises(PDFBridgeError) as exc:
+        PDFBridge()
+    assert "API Key is required" in str(exc.value)
+
+
+def test_init_with_env_api_key(monkeypatch):
+    monkeypatch.setenv("PDFBRIDGE_API_KEY", "pk_test_env")
+    client = PDFBridge()
+    assert client.api_key == "pk_test_env"
+
+
+@responses.activate
+def test_generate_success(client):
+    responses.add(
+        responses.POST,
+        f"{BASE_URL}/convert",
+        json={"message": "Converted successfully", "jobId": "job-123", "statusUrl": "/jobs/job-123"},
+        status=202,
+    )
+    res = client.generate(url="https://example.com")
+    assert isinstance(res, ConvertResponse)
+    assert res.jobId == "job-123"
+
+
+@responses.activate
+def test_generate_auth_error(client):
+    responses.add(
+        responses.POST,
+        f"{BASE_URL}/convert",
+        json={"error": "Unauthorized"},
+        status=401,
+    )
+    with pytest.raises(PDFBridgeError) as exc:
+        client.generate(url="https://example.com")
+    assert "Unauthorized" in str(exc.value)
+    assert exc.value.status_code == 401
+
+
+def test_generate_payload_validation(client):
+    # Missing url, html, or templateId should fail fast locally
+    with pytest.raises(ValueError):
+        client.generate(ghostMode=True)
+
+
+@responses.activate
+def test_generate_ghost_mode(client):
+    binary_pdf = b"%PDF-1.4 mock binary data"
+    responses.add(
+        responses.POST,
+        f"{BASE_URL}/convert",
+        body=binary_pdf,
+        content_type="application/pdf",
+        status=200,
+    )
+    res = client.generate(html="<h1>Secret</h1>", ghostMode=True)
+    assert res == binary_pdf
+
+
+@responses.activate
+def test_generate_and_wait(client):
+    # 1. Mock the initial POST
+    responses.add(
+        responses.POST,
+        f"{BASE_URL}/convert",
+        json={"message": "Accepted", "jobId": "job-abc", "statusUrl": "/jobs/job-abc"},
+        status=202,
+    )
+    # 2. Mock the first Poll (PROCESSING)
+    responses.add(
+        responses.GET,
+        f"{BASE_URL}/jobs/job-abc",
+        json={
+            "id": "job-abc",
+            "status": "PROCESSING",
+            "createdAt": "2026-03-01T12:00:00Z",
+            "updatedAt": "2026-03-01T12:00:01Z"
+        },
+        status=200,
+    )
+    # 3. Mock the final Poll (COMPLETED)
+    responses.add(
+        responses.GET,
+        f"{BASE_URL}/jobs/job-abc",
+        json={
+            "id": "job-abc",
+            "status": "COMPLETED",
+            "pdfUrl": "https://s3.amazonaws.com/bucket/doc.pdf",
+            "createdAt": "2026-03-01T12:00:00Z",
+            "updatedAt": "2026-03-01T12:00:05Z"
+        },
+        status=200,
+    )
+    
+    # Run with tiny poll interval for fast testing
+    res = client.generate_and_wait(url="https://example.com", poll_interval_ms=10)
+    
+    assert isinstance(res, JobStatusResponse)
+    assert res.status == "COMPLETED"
+    assert res.pdfUrl == "https://s3.amazonaws.com/bucket/doc.pdf"