Metadata-Version: 2.4
Name: ulfblk-billing
Version: 0.1.0
Summary: Stripe billing integration: customers, subscriptions, checkout sessions, webhooks
Project-URL: Homepage, https://github.com/abelardodiaz/web25-991-bloques-reciclables
Project-URL: Documentation, https://github.com/abelardodiaz/web25-991-bloques-reciclables/tree/main/packages/python/ulfblk-billing
Project-URL: Repository, https://github.com/abelardodiaz/web25-991-bloques-reciclables
Project-URL: Issues, https://github.com/abelardodiaz/web25-991-bloques-reciclables/issues
Author-email: Abelardo Diaz <abelardo@bloques.dev>
License-Expression: MIT
Keywords: async,billing,checkout,stripe,subscriptions,webhooks
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: ulfblk-core
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# ulfblk-billing

Stripe billing integration: customers, subscriptions, checkout sessions, and webhooks.

## Features

- **Protocol-first**: BillingProvider protocol allows swapping Stripe for Paddle, LemonSqueezy, etc.
- **httpx client**: No Stripe SDK dependency - direct REST API calls with form-encoded bodies
- **Webhook verification**: HMAC-SHA256 signature validation using stdlib (no external deps)
- **Tenant-aware**: Optional multitenant isolation via metadata injection
- **Lifecycle managed**: async context manager with start/stop for httpx client

## Install

```bash
uv add ulfblk-billing
```

## Quick Start

```python
from bloque_billing import (
    BillingService, BillingSettings, CustomerCreate,
    CheckoutCreate, CheckoutMode, StripeProvider,
)

settings = BillingSettings(
    api_key="sk_test_...",
    webhook_secret="whsec_...",
)

provider = StripeProvider(settings)
service = BillingService(provider, settings=settings)

async with service:
    # Create a customer
    customer = await service.create_customer(
        CustomerCreate(email="user@example.com", name="Jane Doe")
    )

    # Create a checkout session
    checkout = await service.create_checkout_session(
        CheckoutCreate(
            customer_id=customer.id,
            price_id="price_xxx",
            success_url="https://example.com/success",
            cancel_url="https://example.com/cancel",
            mode=CheckoutMode.SUBSCRIPTION,
        )
    )
    print(checkout.url)  # redirect user here
```

## Webhook Processing

```python
from bloque_billing import WebhookProcessor, WebhookEventType

processor = WebhookProcessor(webhook_secret="whsec_...")

@processor.on(WebhookEventType.SUBSCRIPTION_CREATED)
async def handle_sub(event):
    print(f"New subscription: {event.data}")

# In your webhook endpoint:
event = await processor.process(payload=body, signature_header=sig)
```

## Custom Provider

Implement the `BillingProvider` protocol for any payment platform:

```python
from bloque_billing.protocol import BillingProvider

class PaddleProvider:
    async def create_customer(self, data):
        ...  # Paddle API calls

    async def health_check(self) -> bool:
        return True

    # ... implement all protocol methods
```

## Dependencies

Only `ulfblk-core` and `httpx`. Webhook verification uses stdlib `hmac`.
