Metadata-Version: 2.4
Name: shelfwatch
Version: 0.1.0
Summary: Official Python SDK for the ShelfWatch APIs v2
Author-email: ShelfWatch <support@shelfwatch.io>
License-Expression: MIT
Project-URL: Homepage, https://shelfwatch.io
Project-URL: Documentation, https://api.shelfwatch.io
Project-URL: Source, https://github.com/ParallelDots/apis-python-sdk
Project-URL: API Docs, https://api.shelfwatch.io
Keywords: shelfwatch,api,sdk,retail,shelf,analytics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
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
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Provides-Extra: publish
Requires-Dist: build>=1.0; extra == "publish"
Requires-Dist: twine>=5.0; extra == "publish"
Dynamic: license-file

# ShelfWatch Python SDK

Official Python client for [ShelfWatch APIs v2](https://api.shelfwatch.io).

```bash
pip install shelfwatch
```

## Quick start

Create credentials in ShelfWatch Console → **Integrations**, then:

```python
from shelfwatch import ShelfWatch

client = ShelfWatch(
    api_key="swpk_…",
    project_id="PROJECT_UUID",
)

visits = client.visits.list(
    start_date="2026-07-01",
    end_date="2026-07-31",
)
print(visits["data"])

detail = client.visits.get(
    visits["data"][0]["visit_uuid"],
    include_kpis=True,
)
```

### OAuth client credentials

```python
client = ShelfWatch(
    client_id="swoc_…",
    client_secret="swocs_…",
    project_id="PROJECT_UUID",
)
# Access tokens are fetched and refreshed automatically.
```

## API coverage

| Resource | Methods |
|----------|---------|
| `client.visits` | `list`, `get` |
| `client.mdm` | `stores`, `users`, `categories`, `brands`, `skus`, `schedules` |
| `client.reports` | `list`, `generate` |

Filters that accept multiple values can be passed as a comma-separated string or a list:

```python
client.visits.list(
    start_date="2026-07-01",
    end_date="2026-07-31",
    visit_status=["completed"],
    store_code=["S001", "S002"],
)

stores = client.mdm.stores(q="delhi")
reports = client.reports.list()
rows = client.reports.generate(
    "visit-level",
    start_date="2026-07-01",
    end_date="2026-07-07",
)
```

Full HTTP reference: ShelfWatch Console → **Help and Support**, or the [apis-v2 docs](https://github.com/ParallelDots/apis-v2).

## Errors

Typed exceptions map to HTTP status codes:

| Exception | Status |
|-----------|--------|
| `ValidationError` | 400 |
| `AuthenticationError` | 401 |
| `ForbiddenError` | 403 |
| `NotFoundError` | 404 |
| `RateLimitError` | 429 |
| `ShelfWatchError` | other |

```python
from shelfwatch import ShelfWatch, NotFoundError

try:
    client.visits.get("missing-uuid")
except NotFoundError as exc:
    print(exc.status_code, exc.message)
```

## Development

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
```

## Publish to PyPI

```bash
./scripts/publish.sh --test   # TestPyPI
./scripts/publish.sh          # PyPI
```

Or manually:

```bash
pip install -e ".[publish]"
python3 -m build
python3 -m twine check dist/*
python3 -m twine upload dist/*
```

Bump `version` in `pyproject.toml` and `shelfwatch/__init__.py` / `client.py` User-Agent before each release.
