Metadata-Version: 2.4
Name: getsnap
Version: 1.10.0
Summary: Official Python SDK for getSnap.dev - Screenshot & PDF API
Author-email: "getSnap.dev" <support@getsnap.dev>
License-Expression: MIT
Project-URL: Homepage, https://getsnap.dev
Project-URL: Documentation, https://getsnap.dev/docs/
Keywords: screenshot,api,pdf,webpage,capture,getsnap
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# getsnap

Official Python SDK for [getSnap.dev](https://getsnap.dev) — Screenshot & PDF API.

Zero dependencies. Uses only Python's standard library (`urllib`).

## Installation

```bash
pip install getsnap
```

## Quick Start

```python
from getsnap import GetSnap

snap = GetSnap("sk_live_YOUR_KEY")

# Take a screenshot
result = snap.screenshot(url="https://github.com", format="png")
print(result["url"])  # CDN URL to your screenshot
```

## Features

- Zero external dependencies (uses `urllib`)
- Python 3.8+
- Screenshot capture (URL or HTML)
- Binary response (raw image bytes)
- Batch capture (up to 100 URLs)
- Usage tracking
- All API parameters supported: `lazy_load`, `wait_for_selector`, `hide_selectors`, `remove_selectors`, `extract_text`, `extract_html`, `click_selector`, `scroll_to_selector`, and more

## API

### `GetSnap(api_key, base_url=None)`

Create a client instance.

- `api_key` — Your getSnap.dev key (starts with `sk_live_` or `sk_test_`)
- `base_url` — Custom base URL (default: `https://api.getsnap.dev`)

### `snap.screenshot(**kwargs)`

Take a screenshot. Returns a dict with `url`, `cached`, `request_id`, and optionally `extracted_text`/`extracted_html`.

```python
result = snap.screenshot(
    url="https://example.com",
    format="png",
    full_page=True,
    remove_popups=True,
    lazy_load=True,
    extract_text=True,
)
print(result["url"])
print(result["extracted_text"])
```

### `snap.screenshot_binary(**kwargs)`

Get raw image/PDF bytes.

```python
data = snap.screenshot_binary(url="https://example.com", format="webp", quality=90)
with open("screenshot.webp", "wb") as f:
    f.write(data)
```

### `snap.og_image(url, **kwargs)`

Generate a 1200x630 Open Graph / Twitter Card image from any URL.
Applies social-share-optimized defaults on the server side (PNG,
hi-DPI, wait for network idle, block popups + ads). Same billing
as `screenshot()`: 1 credit per fresh capture, 0 credits for cache
hits.

```python
result = snap.og_image(url="https://blog.example.com/why-rust")
print(result["url"])  # drop into <meta property="og:image">
```

All defaults are overrideable via kwargs (`viewport_width`,
`viewport_height`, `format`, `device_scale_factor`, `wait_for_selector`,
`extra_delay_ms`, `block_ads`, `remove_popups`, `dark_mode`, `css`).
Pass `response_type="binary"` to get raw bytes with
`Cache-Control: public, max-age=604800, immutable` instead of a JSON
URL.

### `snap.batch(urls, **kwargs)`

Capture multiple URLs in one request.

```python
result = snap.batch(
    urls=["https://github.com", "https://stripe.com", "https://vercel.com"],
    format="png",
    remove_popups=True,
)

print(f"{result['succeeded']}/{result['count']} captured")
for r in result["results"]:
    print(f"{r['source_url']} -> {r['url']}")
```

### `snap.usage()`

Check current usage and quota.

```python
usage = snap.usage()
print(f"{usage['used']}/{usage['limit']} ({usage['plan']})")
```

### `snap.referrals()`

Get your referral code, ready-to-share URL, reward tier, and
aggregated stats. Every getSnap.dev account has a unique code
auto-generated at signup - no opt-in required. When someone signs
up through your referral URL and pays their first invoice, your
Stripe balance is credited by the configured amount (default $5.00).

```python
r = snap.referrals()
print(r["referral_url"])
# https://getsnap.dev/?ref=USERABC1

paid   = r["stats"]["paid"]
earned = r["stats"]["total_earned_cents"] / 100
print(f"{paid} paid conversions, earned ${earned:.2f} lifetime")
```

### `snap.diff(before, after, **kwargs)`

Visual regression diff between two URLs. Captures both at identical
dimensions, compares pixel-by-pixel with pixelmatch, returns
before/after/diff CDN URLs plus a similarity score (0-100).

Billed at 2 credits per fresh diff (1 per captured page). Cache
hits on either side reduce the charge.

```python
r = snap.diff(
    before={"url": "https://staging.example.com/pricing"},
    after={"url":  "https://example.com/pricing"},
)

print(f"Similarity: {r['similarity']:.2f}%")
if r["similarity"] < 99:
    print(f"{r['changed_pixels']} pixels changed:")
    print(f"  Review: {r['diff_url']}")
```

Per-side overrides for slower-loading pages:

```python
r = snap.diff(
    before={
        "url": "https://staging.example.com",
        "wait_for_selector": "#pricing-table",
        "extra_delay_ms": 500,
    },
    after={"url": "https://example.com"},
    viewport_width=1440,
    threshold=0.05,  # more sensitive than default 0.1
)
```

### `snap.status(request_id)`

Check status of an async (webhook) request.

```python
status = snap.status("req_abc123")
```

## Error Handling

```python
from getsnap import GetSnap, GetSnapError

snap = GetSnap("sk_live_YOUR_KEY")

try:
    snap.screenshot(url="https://example.com", format="png")
except GetSnapError as e:
    print(e.status, e.error, str(e))
    # 402, "quota_exceeded", "Monthly limit reached..."
```

## License

MIT
