pdfbridge-python 1.0.0__py3-none-any.whl

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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,6 @@
+pdfbridge/__init__.py,sha256=aV3cJpMXhk_RXu3EAvOJ_IMWoUybpC7W9lXmq2Ymuvs,414
+pdfbridge/client.py,sha256=oOY1XacKb-SOM_t-xtbz_x-OUwNZwvD8IM3OwYuESRA,4938
+pdfbridge/models.py,sha256=LRVjzMNohHyDHsvsh0H2cJrTSdKhZE5LTxll8EgTXoE,2427
+pdfbridge_python-1.0.0.dist-info/METADATA,sha256=Hu29oeHmh1IFq8hRLQQE1COWogh7MORG6_cZbi1OL6I,4126
+pdfbridge_python-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pdfbridge_python-1.0.0.dist-info/RECORD,,

pdfbridge_python-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any