# GrowFlow Billing Client

Python client for [GrowFlow Billing API](https://billing.growflow.studio) - subscription management, checkout sessions, invoices, and more.

> **Documentation**: See [growflow-billing-docs](https://github.com/growflow/growflow-billing-docs) for complete API documentation and examples.
>
> **Node.js**: Looking for the Node.js/TypeScript client? See [@growflow/billing-client](https://github.com/growflow/growflow-billing-client-node).

## Installation

```bash
pip install growflow-billing-client
```

Or install from source:

```bash
pip install git+https://github.com/growflow/growflow-billing-client.git
```

## Quick Start

```python
import asyncio
from growflow_billing import GrowFlowBillingClient

async def main():
    async with GrowFlowBillingClient(api_key="sk_live_xxx") as client:
        # Get available plans
        plans = await client.get_plans()
        for plan in plans:
            print(f"{plan.name}: {plan.price_monthly} {plan.currency}/month")

        # Create a checkout session
        session = await client.create_checkout_session(
            customer_external_id="customer_123",
            plan_slug="pro",
            billing_cycle="monthly",
            success_url="https://yourapp.com/billing?status=success",
            cancel_url="https://yourapp.com/billing?status=canceled",
        )
        print(f"Checkout URL: {session.checkout_url}")

asyncio.run(main())
```

## Features

- **Plans**: List available subscription plans
- **Subscribers**: Create and manage subscribers
- **Subscriptions**: Get subscription status, cancel, change plans
- **Checkout**: Create Stripe checkout sessions
- **Portal**: Create Stripe customer portal sessions
- **Invoices**: List invoice history with PDF downloads
- **Products**: List and purchase add-on products

## API Reference

### Client Initialization

```python
from growflow_billing import GrowFlowBillingClient

client = GrowFlowBillingClient(
    api_key="sk_live_xxx",                              # Required
    base_url="https://billing.growflow.studio/api/v1", # Optional
    timeout=30.0,                                       # Optional (seconds)
    max_retries=3,                                      # Optional
)
```

### Plans

```python
# List all active plans
plans = await client.get_plans()

# Access plan properties
for plan in plans:
    print(plan.slug)           # e.g., "pro"
    print(plan.name)           # e.g., "Pro Plan"
    print(plan.price_monthly)  # e.g., Decimal("349.00")
    print(plan.price_yearly)   # e.g., Decimal("3490.00")
    print(plan.limits)         # e.g., {"conversations": 5000, "stores": 3}
    print(plan.features)       # e.g., ["premium_support", "api_access"]
    print(plan.trial_days)     # e.g., 14
```

### Subscribers

```python
# Create a new subscriber
subscriber = await client.create_subscriber(
    external_id="store_123",      # Your internal ID
    email="owner@store.com",
    name="My Store",
    company_name="Store Inc.",    # Optional
    vat_number="IT12345678901",   # Optional
)

# Get subscriber by external ID
subscriber = await client.get_subscriber(external_id="store_123")
```

### Subscriptions

```python
# Get active subscription
subscription = await client.get_subscription(external_id="store_123")

if subscription:
    print(subscription.status)              # "active", "trialing", "past_due", etc.
    print(subscription.plan_slug)           # "pro"
    print(subscription.billing_cycle)       # "monthly" or "yearly"
    print(subscription.current_period_end)  # datetime
    print(subscription.is_trialing)         # bool
    print(subscription.trial_days_remaining) # int or None

# Cancel subscription
await client.cancel_subscription(
    subscription_id="sub_xxx",
    at_period_end=True,  # Cancel at end of billing period
)

# Change plan
await client.change_plan(
    subscription_id="sub_xxx",
    new_plan_slug="enterprise",
    prorate=True,
)
```

### Checkout Sessions

```python
# Create checkout session for new subscription
session = await client.create_checkout_session(
    customer_external_id="store_123",
    plan_slug="pro",
    billing_cycle="monthly",  # or "yearly"
    success_url="https://yourapp.com/billing?status=success",
    cancel_url="https://yourapp.com/billing?status=canceled",
    coupon_code="WELCOME20",  # Optional discount code
)

# Redirect user to Stripe checkout
redirect_url = session.checkout_url
```

### Customer Portal

```python
# Create portal session for subscription management
portal = await client.create_portal_session(
    customer_external_id="store_123",
    return_url="https://yourapp.com/billing",
)

# Redirect user to Stripe portal
redirect_url = portal.portal_url
```

### Invoices

```python
# List invoices
invoices = await client.get_invoices(
    external_id="store_123",
    limit=20,
)

for invoice in invoices:
    print(invoice.number)            # "INV-0001"
    print(invoice.status)            # "paid", "open", "void"
    print(invoice.amount_paid)       # 34900 (cents)
    print(invoice.currency)          # "eur"
    print(invoice.invoice_pdf)       # URL to PDF
    print(invoice.hosted_invoice_url) # Stripe hosted page
```

## Error Handling

```python
from growflow_billing import (
    GrowFlowBillingError,
    AuthenticationError,
    NotFoundError,
    ConflictError,
    ValidationError,
    RateLimitError,
)

try:
    plans = await client.get_plans()
except AuthenticationError:
    print("Invalid API key")
except NotFoundError as e:
    print(f"Resource not found: {e.message}")
except RateLimitError:
    print("Rate limit exceeded, try again later")
except GrowFlowBillingError as e:
    print(f"API error: {e.message} (status: {e.status_code})")
```

## Configuration

Environment variables:

```bash
GROWFLOW_BILLING_API_KEY=sk_live_xxx
GROWFLOW_BILLING_URL=https://billing.growflow.studio/api/v1
```

## License

MIT License - see [LICENSE](LICENSE) for details.
