Metadata-Version: 2.4
Name: coffrify
Version: 0.2.0
Summary: Official Python SDK for Coffrify — encrypted file transfer infrastructure.
Project-URL: Homepage, https://coffrify.com
Project-URL: Documentation, https://docs.coffrify.dev
Project-URL: Repository, https://github.com/coffrify/coffrify-python
Project-URL: Issues, https://github.com/coffrify/coffrify-python/issues
Author-email: Coffrify <support@coffrify.com>
License: MIT
License-File: LICENSE
Keywords: coffrify,encrypted,file-transfer,sdk,webhooks
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Requires-Dist: requests>=2.31.0
Requires-Dist: typing-extensions>=4.0.0; python_version < '3.11'
Description-Content-Type: text/markdown

# coffrify

Official Python SDK for **Coffrify** — encrypted file transfer infrastructure.

## Install

```bash
pip install coffrify
# or with uv
uv add coffrify
# or with poetry
poetry add coffrify
```

Requires Python 3.9+.

## Quickstart

```python
from coffrify import Coffrify

client = Coffrify(api_key="cfy_live_...")  # or set COFFRIFY_API_KEY env var

# Create a transfer
result = client.transfers.create(
    files=[{"name": "rapport.pdf", "size": 1_240_000, "mime_type": "application/pdf"}],
    expires_in_hours=72,
    max_downloads=10,
    password="secret",
)
print(result["share_url"])

# List webhooks
webhooks = client.webhooks.list()

# Subscribe to a webhook (secret returned ONCE)
created = client.webhooks.create(
    name="Production",
    url="https://app.example.com/hooks/coffrify",
    events=["transfer.created", "transfer.downloaded"],
)
print("SAVE THIS SECRET:", created["secret"])
```

## Webhook signature verification

```python
from flask import Flask, request, abort
from coffrify.webhooks import verify

app = Flask(__name__)

@app.post("/hooks/coffrify")
def webhook():
    result = verify(
        raw_body=request.data.decode("utf-8"),
        signature_header=request.headers.get("X-Coffrify-Signature"),
        secret=os.environ["COFFRIFY_WEBHOOK_SECRET"],
    )
    if not result.valid:
        abort(400, result.reason)

    event = result.event
    if event["type"] == "transfer.downloaded":
        # ...
        pass
    return ("", 200)
```

The signature header `X-Coffrify-Signature: t=<ts>,v1=<hex>` is verified with constant-time comparison and a ±5 minute timestamp tolerance.

## Auto-retry & Idempotency

The SDK auto-injects `Idempotency-Key` headers on every POST/PUT/PATCH/DELETE for safe retries. Network errors and 5xx/429 responses retry up to 3 times with exponential backoff.

Disable with `Coffrify(api_key=..., max_retries=0, auto_idempotency=False)`.

## Auth

Authentication uses Bearer tokens with your API key:

- **Live keys**: `cfy_<64 hex>` — production data
- **Test keys**: `cfy_test_<64 hex>` — sandbox

```python
key = client.api_keys.create(
    name="CI deploy bot",
    scopes=["transfers:write", "webhooks:manage"],
    expires_in_days=90,
    allowed_ips=["1.2.3.4/32"],
)
print("SAVE:", key["key"])
```

## License

MIT
