Metadata-Version: 2.4
Name: storyflo
Version: 1.0.1
Summary: Official Python client for the Storyflo audio news API
Author-email: Storyflo <hello@storyflo.com>
License: MIT
Project-URL: Homepage, https://storyflo.com/developers
Project-URL: Repository, https://github.com/Alisammour/storyflo-sdk
Keywords: storyflo,audio,news,tts,x402,mcp,agentkit
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: ruff>=0.7; extra == "dev"

# storyflo (Python)

Official Python client for the [Storyflo](https://storyflo.com) audio
news API. Wraps the six agent tools across all three protocols
(public REST, OAuth 2.1, x402 micropayments).

```bash
pip install storyflo
```

## Usage

```python
from storyflo import StoryfloClient

# Public read — no auth, rate-limited per IP.
sf = StoryfloClient()

trending = sf.search_articles(vertical="tech", limit=5)
for a in trending["articles"]:
    audio = sf.get_audio_url(a["slug"])
    print(f"{a['title']} → {audio['audio_url']}")
```

### OAuth (Claude / ChatGPT agents)

```python
import os

sf = StoryfloClient(auth=("bearer", os.environ["STORYFLO_OAUTH_TOKEN"]))

sf.subscribe_topic(["tech", "finance"])
digest = sf.digest(window="24h", limit=5)
```

### x402 micropayments (Coinbase AgentKit)

```python
# `payment_header` is the base64-encoded EIP-712 authorization the
# AgentKit produces on settle. Each call costs $0.001-$0.30 USDC.
sf = StoryfloClient(auth=("x402", payment_header))
article = sf.get_article("interest-rates-q1")
```

## API

| Method                          | Tool                  | Auth required        |
|---------------------------------|-----------------------|----------------------|
| `search_articles(...)`          | `search_articles`     | none / x402          |
| `get_article(slug)`             | `get_article`         | none / x402          |
| `get_audio_url(slug)`           | `get_audio_url`       | OAuth / x402         |
| `subscribe_topic(verticals)`    | `subscribe_topic`     | OAuth (write scope)  |
| `list_subscriptions()`          | `list_subscriptions`  | OAuth (read scope)   |
| `digest(window, limit, ...)`    | `digest`              | OAuth / x402         |

Errors raise `StoryfloError` with `.status` and parsed `.body`.

## License

MIT
