Metadata-Version: 2.4
Name: socialstats-sdk
Version: 0.1.0
Summary: Official Python client for the Socialstats Enterprise API
Project-URL: Homepage, https://socialstats.com
Project-URL: API, https://api.socialstats.com
Author: Songstats
License: MIT
License-File: LICENSE
Keywords: api,creators,sdk,social,socialstats
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx<1.0.0,>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest<9.0.0,>=8.0.0; extra == 'dev'
Requires-Dist: respx<1.0.0,>=0.21.0; extra == 'dev'
Description-Content-Type: text/markdown

# Socialstats Python SDK

Official Python client for the **Socialstats Enterprise API**.

API Base URL: https://api.socialstats.com  
API Key Access: Please contact api@socialstats.com

---

## Requirements

- Python >= 3.10

---

## Installation

Install from PyPI:

    pip install socialstats-sdk

For local development:

    pip install -e ".[dev]"

---

## Quick Start

```python
from socialstats_sdk import SocialstatsClient

client = SocialstatsClient(api_key="YOUR_API_KEY")

# API status
status = client.info.status()

# Creator information
creator = client.creators.info(socialstats_creator_id="abcd1234")

# Creator statistics
creator_stats = client.creators.stats(
    socialstats_creator_id="abcd1234",
    source="instagram",
)

# Post statistics
post_stats = client.posts.stats(
    socialstats_creator_id="abcd1234",
    source_id="instagram",
    post_id="1234567890",
)
```

---

## Authentication

All requests include your API key in the `apikey` header.

You can request an API key by contacting api@socialstats.com.

We recommend storing your key securely in environment variables:

    export SOCIALSTATS_API_KEY=your_key_here

---

## Available Resource Clients

- `client.info`
- `client.creators`
- `client.posts`

Info endpoints:
- `client.info.sources()` -> `/sources`
- `client.info.status()` -> `/status`
- `client.info.uptime_check()` -> `/uptime_check`
- `client.info.definitions()` -> `/definitions`

Creator endpoints:
- `client.creators.info(...)` -> `/creators/info`
- `client.creators.stats(...)` -> `/creators/stats`
- `client.creators.historic_stats(...)` -> `/creators/historic_stats`
- `client.creators.audience(...)` -> `/creators/audience`
- `client.creators.audience_details(country_code=..., ...)` -> `/creators/audience/details`
- `client.creators.activities(...)` -> `/creators/activities`
- `client.creators.content(...)` -> `/creators/content`
- `client.creators.top_posts(...)` -> `/creators/top_posts`
- `client.creators.search(q=..., ...)` -> `/creators/search`
- `client.creators.add_link_request(link=..., ...)` -> `/creators/link_request`
- `client.creators.remove_link_request(link=..., ...)` -> `/creators/link_request`

Post endpoints:
- `client.posts.stats(...)` -> `/posts/stats`
- `client.posts.historic_stats(...)` -> `/posts/historic_stats`

---

## Error Handling

```python
from socialstats_sdk import SocialstatsAPIError, SocialstatsTransportError

try:
    client.creators.info(socialstats_creator_id="invalid")
except SocialstatsAPIError as exc:
    print(f"API error: {exc}")
except SocialstatsTransportError as exc:
    print(f"Transport error: {exc}")
```

---

## Development

To work on the SDK locally:

    git clone https://github.com/songstats/socialstats-python-sdk.git
    cd socialstats-python-sdk
    pip install -e ".[dev]"
    pytest

---

## Versioning

This SDK follows Semantic Versioning (SemVer).

---

## License

MIT
