Metadata-Version: 2.4
Name: solari-sdk
Version: 0.2.0
Summary: Python client for the SOLARI API — creator and brand intelligence across Instagram and TikTok.
License-Expression: MIT
Project-URL: Homepage, https://solari.sh
Project-URL: Documentation, https://solari.sh/api
Keywords: solari,brandazine,instagram,tiktok,creator,influencer,brand,sdk,api-client
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# solari-sdk

Python client for the [SOLARI API](https://solari.sh/api) — creator and brand intelligence across Instagram and TikTok. Standard library only; Python 3.9+; ships `py.typed`.

```
pip install solari-sdk
```

## Quickstart

```python
from solari_sdk import Solari

solari = Solari()  # reads SOLARI_TOKEN; or Solari(token="...")

hits = solari.tools.catalog.instagram.account.search(query="nike", limit=3)
brand = solari.tools.insight.instagram.brand.overview(username="nike")
tools = solari.list_tools()
```

Get a token with `solari auth token` on a machine that is signed in to the [solari CLI](https://solari.sh/docs), or use a token you already hold from an MCP connector.

## Typed tools

`solari.tools` is generated from the SOLARI tool registry: every tool is a real method with keyword-only, typed parameters (`Literal[...]` for enums), so pyright and mypy catch a missing required argument, a misspelled keyword, or a wrong enum value before anything runs, and your editor completes the paths.

```python
solari.tools.catalog.instagram.account.search(query="nike", query_type="bio")
solari.tools.catalog.instagram.account.search(limit=3)  # type checker: missing "query"
solari.tools.catalog.instagram.account.search(query="nike", query_type="fuzzy")  # type checker: not a Literal value
```

Tool responses are JSON (`Any`) whose shape is documented per tool at [solari.sh/docs](https://solari.sh/docs).

`solari.call(name, arguments=None, **kwargs)` runs any tool by name, including the per-account `solari_apps_*` tools that are not in the generated catalog; `solari.dynamic.<any>.<path>(**kwargs)` spells such a call as a path without type checking.

## API

- `Solari(token=None, base_url="https://solari.sh", timeout=150, user_agent=None, transport=None)`
- `tools.<family>.<platform>.<group>.<name>(**kwargs)` — typed tool calls; segments mirror the `solari_` tool names.
- `call(name, arguments=None, **kwargs)` — run a tool by name and get its JSON payload back.
- `list_tools()` — every tool the signed-in account can call, with its JSON input schema.
- `get_tool(name)` — one tool.
- `me()` — the identity behind the token.
- `dynamic` — untyped path proxy for tools that are not in the generated catalog.
- `SOLARI_TOOL_NAMES`, `SolariTools` — the generated catalog.

Errors raise `SolariError` with `status`, `code`, `message`, `tool`, `retry_after_seconds`, and a `retryable` property (429, 502, 503, 504).

## Development

```
python3 -m unittest discover -s tests -v
uvx pyright
uvx mypy --strict solari_sdk tests/typed_usage.py
```

`solari_sdk/_tools.py` is produced from the MCP worker's tool registry by `pnpm run sdk:generate` in `cf-workers/solari-mcp`; CI fails when it is stale.
