# Synup Python SDK

Python SDK for the [Synup API](https://docs.synup.com). Install with pip and call the API using your API key.

## Installation

```bash
pip install synup-sdk
```

For local development from the engineering-scripts repo:

```bash
pip install -e synup-sdk
```

## Configuration

Create a client with your API key. You can generate API keys from your Synup workspace: **Settings → Integrations → Generate**.

```python
from synup import SynupClient

client = SynupClient(api_key="YOUR_API_KEY")
```

Optional: use a custom base URL (default is `https://api.synup.com`):

```python
client = SynupClient(api_key="YOUR_API_KEY", base_url="https://api.synup.com")
```

## Fetch all locations

### Single page (with pagination)

Get one page of locations and use the returned cursors to paginate:

```python
result = client.fetch_all_locations(first=10)

# List of location dicts
locations = result["locations"]

# Pagination info
page_info = result["page_info"]
# page_info["has_next_page"], page_info["has_previous_page"]
# page_info["start_cursor"], page_info["end_cursor"]

# Next page
if page_info["has_next_page"]:
    next_result = client.fetch_all_locations(first=10, after=page_info["end_cursor"])
```

### All locations (auto-paginate)

Fetch every location in one call; the SDK will follow cursors until all are retrieved:

```python
all_locations = client.fetch_all_locations(fetch_all=True)
# all_locations is a list of location dicts
```

Optional: set page size when using `fetch_all=True` (default is 100):

```python
all_locations = client.fetch_all_locations(fetch_all=True, page_size=50)
```

## Errors

On non-2xx API responses, the client raises `SynupAPIError`:

```python
from synup import SynupClient, SynupAPIError

client = SynupClient(api_key="...")
try:
    client.fetch_all_locations()
except SynupAPIError as e:
    print(e.status_code, e.response_body)
```

## Version

Current version: 0.1.0

## Publishing (deploy)

The SDK is published to PyPI using **GitHub Actions** in the engineering-scripts repo.

- **Tests**: Run automatically on PRs and pushes that touch `synup-sdk/`.
- **Publish (staging)**: In the engineering-scripts repo go to **Actions → synup-sdk → Run workflow**, choose **testpypi**, and run. Add repo secret `TEST_PYPI_API_TOKEN` (Test PyPI API token).
- **Publish (production)**: Same flow, choose **pypi**. Add repo secret `PYPI_API_TOKEN` (PyPI API token).

After publishing to Test PyPI, install with:  
`pip install --index-url https://test.pypi.org/simple/ synup-sdk`
