|
| 1 | +# Migration Guide: v2.x to v3.0 |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +Version 3.0.0 introduces SSRF protection and removes client-side PDF parsing. |
| 6 | + |
| 7 | +## Key Changes |
| 8 | + |
| 9 | +### 1. `sign()` No Longer Accepts URLs (API Limitation) |
| 10 | + |
| 11 | +**Before (v2.x)**: |
| 12 | +```python |
| 13 | +result = await client.sign('https://example.com/document.pdf', {...}) |
| 14 | +``` |
| 15 | + |
| 16 | +**After (v3.0)** - Fetch file first: |
| 17 | +```python |
| 18 | +import httpx |
| 19 | + |
| 20 | +async with httpx.AsyncClient() as http: |
| 21 | + url = 'https://example.com/document.pdf' |
| 22 | + |
| 23 | + # IMPORTANT: Validate URL |
| 24 | + if not url.startswith('https://trusted-domain.com/'): |
| 25 | + raise ValueError('URL not from trusted domain') |
| 26 | + |
| 27 | + response = await http.get(url, timeout=10.0) |
| 28 | + response.raise_for_status() |
| 29 | + pdf_bytes = response.content |
| 30 | + |
| 31 | +result = await client.sign(pdf_bytes, {...}) |
| 32 | +``` |
| 33 | + |
| 34 | +### 2. Most Methods Now Accept URLs (Passed directly to DWS) |
| 35 | + |
| 36 | +Good news! These methods now support URLs passed securely to the DWS: |
| 37 | +- `rotate()`, `split()`, `add_page()`, `duplicate_pages()`, `delete_pages()` |
| 38 | +- `set_page_labels()`, `set_metadata()`, `optimize()` |
| 39 | +- `flatten()`, `apply_instant_json()`, `apply_xfdf()` |
| 40 | +- All redaction methods |
| 41 | +- `convert()`, `ocr()`, `watermark_*()`, `extract_*()`, `merge()`, `password_protect()` |
| 42 | + |
| 43 | +**Example**: |
| 44 | +```python |
| 45 | +# This now works! |
| 46 | +result = await client.rotate('https://example.com/doc.pdf', 90, pages={'start': 0, 'end': 5}) |
| 47 | +``` |
| 48 | + |
| 49 | +### 3. Negative Page Indices Now Supported |
| 50 | + |
| 51 | +Use negative indices for "from end" references: |
| 52 | +- `-1` = last page |
| 53 | +- `-2` = second-to-last page |
| 54 | +- etc. |
| 55 | + |
| 56 | +**Examples**: |
| 57 | +```python |
| 58 | +# Rotate last 3 pages |
| 59 | +await client.rotate(pdf, 90, pages={'start': -3, 'end': -1}) |
| 60 | + |
| 61 | +# Delete first and last pages |
| 62 | +await client.delete_pages(pdf, [0, -1]) |
| 63 | + |
| 64 | +# Split: keep middle pages, excluding first and last |
| 65 | +await client.split(pdf, [{'start': 1, 'end': -2}]) |
| 66 | +``` |
| 67 | + |
| 68 | +### 4. Removed from Public API |
| 69 | + |
| 70 | +- `process_remote_file_input()` - No longer needed (URLs passed to server) |
| 71 | +- `get_pdf_page_count()` - Use negative indices instead |
| 72 | +- `is_valid_pdf()` - Let server validate (internal use only) |
| 73 | + |
| 74 | +**Still Available:** |
| 75 | +- `is_remote_file_input()` - Helper to detect if input is a URL (still public) |
0 commit comments