growflowbilling-client 1.2.0__tar.gz

growflowbilling_client-1.2.0/.gitignore

@@ -0,0 +1,66 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+venv/
+ENV/
+env/
+.venv
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+*.cover
+
+# Database
+*.db
+
+# Logs
+*.log
+
+# Alembic
+# Uncommit migrations/versions/ in production
+
+# Node (for admin dashboard)
+node_modules/
+.pnpm-store/
+dist/
+build/
+
+# Exception: keep admin-dashboard src/lib
+!platform/admin-dashboard/src/lib/
+
+full-version/

growflowbilling_client-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 GrowFlow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

growflowbilling_client-1.2.0/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.4
+Name: growflowbilling-client
+Version: 1.2.0
+Summary: Python client for GrowFlow Billing API - subscription management, checkout, invoices
+Project-URL: Homepage, https://github.com/giuliogarofalo/growflow-billing
+Project-URL: Documentation, https://docs.growflow.studio/billing-client
+Project-URL: Repository, https://github.com/giuliogarofalo/growflow-billing
+Author-email: GrowFlow <dev@growflow.studio>
+License: MIT
+License-File: LICENSE
+Keywords: billing,payments,saas,stripe,subscriptions
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic[email]>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: respx>=0.20.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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.

growflowbilling_client-1.2.0/PUBLISHING.md

@@ -0,0 +1,73 @@
+# 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()
+```

growflowbilling_client-1.2.0/README.md

@@ -0,0 +1,216 @@
+# 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.

growflowbilling_client-1.2.0/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "growflowbilling-client"
+version = "1.2.0"
+description = "Python client for GrowFlow Billing API - subscription management, checkout, invoices"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "GrowFlow", email = "dev@growflow.studio"}
+]
+keywords = ["billing", "subscriptions", "stripe", "payments", "saas"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "pydantic[email]>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "respx>=0.20.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/giuliogarofalo/growflow-billing"
+Documentation = "https://docs.growflow.studio/billing-client"
+Repository = "https://github.com/giuliogarofalo/growflow-billing"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/growflow_billing"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]