# Publishing growflowbilling-client (Python SDK)

## Overview

The Python SDK is published to PyPI as `growflowbilling-client`.
Publishing is automated via GitHub Actions on push to `main` when files in `sdk/python/` change.

**Note**: The distribution name is `growflowbilling-client` but the Python import path remains `growflow_billing`:

```python
from growflow_billing import GrowFlowBillingClient
```

## How It Works

1. **Version detection**: CI compares `pyproject.toml` version against the published PyPI version
2. **If version changed**: lint, type-check, test, build, publish to PyPI, create git tag
3. **If version unchanged**: CI skips publishing

## Publishing a New Version

```bash
cd sdk/python

# 1. Make your changes
# 2. Bump version in pyproject.toml
#    version = "1.3.0"

# 3. Commit and push
git add pyproject.toml
git commit -m "chore(sdk): bump python SDK to vX.Y.Z"
git push origin main
```

CI will automatically:
- Run `ruff` linting and `mypy` type checking
- Run `pytest`
- Build with `python -m build`
- Publish to PyPI via OIDC Trusted Publisher (no tokens needed)
- Create a git tag `growflowbilling-python-sdk-vX.Y.Z`

## PyPI Trusted Publisher (OIDC)

Publishing uses PyPI's Trusted Publisher mechanism — no API tokens required.

**Setup (one-time, already done):**
1. PyPI → Manage → Publishing → Add trusted publisher for `growflowbilling-client`
   - Owner: `giuliogarofalo`, Repo: `growflow-billing`, Workflow: `publish-python-sdk.yml`, Environment: `pypi`
2. GitHub → `growflow-billing` repo → Settings → Environments → Create `pypi` environment

## Local Development

```bash
cd sdk/python
pip install -e ".[dev]"
ruff check src/        # Linting
mypy src/              # Type checking
pytest                 # Tests
python -m build        # Build sdist + wheel
```

## Consumer Usage

```bash
pip install growflowbilling-client
```

```python
from growflow_billing import GrowFlowBillingClient

async with GrowFlowBillingClient(api_key="sk_...") as client:
    plans = await client.get_plans()
```
