Metadata-Version: 2.4
Name: citeflow-python
Version: 0.1.1
Summary: Official Python SDK for the CiteFlow API (SEO, AEO, GEO audits).
Project-URL: Homepage, https://citeflow.io
Project-URL: Documentation, https://citeflow.io/help/partner-api
Author-email: CiteFlow <support@citeflow.io>
License-Expression: MIT
License-File: LICENSE
Keywords: aeo,api,audit,citeflow,geo,sdk,seo
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-mock>=3.12; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: responses>=0.25; extra == 'dev'
Description-Content-Type: text/markdown

# citeflow-python

Official Python SDK for the **[CiteFlow](https://citeflow.io)** Partner
API — programmatic SEO, AEO, and GEO audits.

[CiteFlow](https://citeflow.io) is an AI-visibility scanner: it audits how
well a website can be crawled, understood, and cited by AI search engines
(ChatGPT, Claude, Perplexity, Google AI Overviews). This SDK lets partners
run those audits from their own products via the CiteFlow Partner API.

- Website: <https://citeflow.io>
- API docs & getting started: <https://citeflow.io/help/partner-api>
- Dashboard (API keys, billing, webhooks): <https://citeflow.io/dashboard/api>

## Install

```bash
pip install citeflow-python
```

Python 3.9+ required. Depends on `requests`.

## Quickstart

```python
import os
from citeflow import Citeflow

client = Citeflow(api_key=os.environ["CITEFLOW_API_KEY"])

# Create an audit and wait for the result (~30s for SEO).
audit = client.audits.create(url="https://example.com", type="seo")
result = client.audits.wait_for_completion(audit["audit_id"], timeout=90)

if result["status"] == "complete":
    print("Scores:", result["scores"])
elif result["status"] == "failed":
    print("Failure:", result["failure_reason"])

# Check remaining balance.
b = client.balance.retrieve()
print(f"Balance: {b['balance_usd']} ({b['balance']} credits)")
```

## Features

- **Auto-retry** on `429` and `5xx` with exponential back-off + jitter.
  Honors `Retry-After`.
- **Auto Idempotency-Key** on every POST — safe to retry on network
  failure without double-charging.
- **`wait_for_completion`** polling helper with configurable timeout.
- **HMAC webhook verification** with timestamp tolerance + rotation
  grace handling.
- Pluggable `requests.Session` for custom proxies / adapters.

## Webhook verification

```python
from citeflow import verify_webhook_signature, parse_webhook_event, CiteflowSignatureError

# In your webhook handler (Flask, FastAPI, Django, …):
raw_body = request.get_data()  # bytes — do NOT JSON-parse first
try:
    event = parse_webhook_event(
        raw_body=raw_body,
        headers=request.headers,
        secret=os.environ["CITEFLOW_WEBHOOK_SECRET"],
    )
    # event["type"] in {"audit.completed", "audit.failed", "audit.cancelled", "balance.low"}
    print(event["id"], event["type"], event["data"])
    return "", 200
except CiteflowSignatureError:
    return "", 400
```

## Errors

```python
from citeflow import CiteflowError

try:
    client.audits.create(url="invalid", type="seo")
except CiteflowError as err:
    print(err.code, err.request_id)
    if err.code == "INSUFFICIENT_CREDITS":
        print(f"Need {err.required} more credits")
```

Full error catalog: https://citeflow.io/help/partner-api#troubleshooting.

## Configuration

```python
client = Citeflow(
    api_key="ckf_…",
    base_url="https://www.citeflow.io/api/v1",  # default; override only for staging/self-hosted
    timeout=30.0,                            # per-request seconds
    max_retries=3,                           # for 429 + 5xx + network
)
```

## License

MIT. CiteFlow API itself is a paid service — see
https://citeflow.io/terms-of-service.
