eldercrank-stripe 0.1.0b1
A no-nonsense Stripe integration by a grumpy dev.
License: MIT
Requires Python: >=3.13
Keywords: api-wrapper, payment-processing, stripe, webhooks

# Eldercrank Stripe

A lightweight, no-nonsense Python wrapper for the Stripe API, providing centralized interfaces for handling Stripe events and interactions.

## Features

- **StripeManager**: Focused on data operations (products, prices, customers, subscriptions).
- **StripeHandler**: Specialized for webhook handling and event processing.
- **Clean Separation**: Clear distinction between data operations and webhook processing.
- **Framework Agnostic**: Designed to work with any web framework.
- **Comprehensive API Coverage**: Full support for common Stripe operations.

## Quick Start

### Installation

This project uses `uv` for dependency management.

```bash
uv add eldercrank-stripe
```

### Basic Usage

Here's a quick example to get you started:

```python
from eldercrank.stripe import StripeManager

# Initialize the manager with your API key
manager = StripeManager(api_key="your_stripe_api_key")

# Create a product
product = manager.create_product(
    name="Premium Plan",
    description="Access to premium features"
)

# Create a price
price = manager.create_price(
    product_id=product["id"],
    unit_amount=2999,  # $29.99
    currency="usd",
    recurring={"interval": "month"}
)

# Create a customer
customer = manager.create_customer(
    name="John Doe",
    email="john@example.com"
)

# Create a subscription
subscription = manager.create_subscription(
    customer_id=customer["id"],
    price_id=price["id"]
)

print(f"Subscription created: {subscription['id']}")
```

## Usage

### Stripe Manager (Data Operations)

Use `StripeManager` for all data-related operations:

```python
from eldercrank.stripe import StripeManager

manager = StripeManager(api_key="your_stripe_api_key")

# Create a product
product = manager.create_product(
    name="Premium Plan",
    description="Access to premium features"
)

# Create a price
price = manager.create_price(
    product_id=product["id"],
    unit_amount=2999,  # $29.99
    currency="usd",
    recurring={"interval": "month"}
)

# Create a customer
customer = manager.create_customer(
    name="John Doe",
    email="john@example.com"
)

# Create a subscription
subscription = manager.create_subscription(
    customer_id=customer["id"],
    price_id=price["id"]
)
```

### Stripe Handler (Webhook Processing)

Use `StripeHandler` for webhook processing:

```python
from eldercrank.stripe import StripeHandler

handler = StripeHandler(
    api_key="your_stripe_api_key",
    webhook_secret="your_webhook_secret"
)

# Register event handlers
def handle_payment_success(event_data):
    print(f"Payment succeeded: {event_data.get('id')}")

handler.add_event_handler("payment_intent.succeeded", handle_payment_success)

# Process incoming webhook
# event = handler.process_webhook(payload, signature)
```

### Web Framework Integration

For web framework integration, use the companion libraries:

- **FastAPI**: `eldercrank-stripe-fastapi`
- **Flask**: `eldercrank-stripe-flask`

## API Reference

### StripeManager

#### Product Operations
- `create_product(name, description=None, active=True, metadata=None)`
- `retrieve_product(product_id)`
- `update_product(product_id, name=None, description=None, active=None, metadata=None)`
- `delete_product(product_id)` (deactivates the product)
- `list_products(active=None, limit=10)`

#### Price Operations
- `create_price(product_id, unit_amount, currency="usd", recurring=None, nickname=None, active=True)`
- `retrieve_price(price_id)`
- `update_price(price_id, active=None, nickname=None)`
- `delete_price(price_id)` (deactivates the price)
- `list_prices(active=None, product_id=None, limit=10)`

#### Customer Operations
- `create_customer(name=None, email=None, description=None, phone=None, address=None, metadata=None)`
- `retrieve_customer(customer_id)`
- `update_customer(customer_id, name=None, email=None, description=None, phone=None, address=None, metadata=None)`
- `delete_customer(customer_id)`
- `list_customers(limit=10)`

#### Subscription Operations
- `create_subscription(customer_id, price_id, trial_period_days=None, metadata=None)`
- `retrieve_subscription(subscription_id)`
- `update_subscription(subscription_id, price_id=None, proration_behavior="create_prorations", metadata=None)`
- `cancel_subscription(subscription_id, at_period_end=False)`
- `list_subscriptions(customer_id=None, status=None, limit=10)`

#### Webhook Operations
- `add_webhook_handler(event_name, handler)`
- `remove_webhook_handler(event_name)`
- `process_webhook_payload(payload, signature, webhook_secret)`

### StripeHandler

- `add_event_handler(event_name, handler)`
- `remove_event_handler(event_name)`
- `process_webhook(payload, signature)`

## Development

### Prerequisites

- Python 3.13+
- [uv](https://github.com/astral-sh/uv) package manager

### Setup

```bash
# Clone the repository
git clone <repository-url>
cd eldercrank-stripe

# Install dependencies
uv sync

# Install pre-commit hooks
uv run pre-commit install
```

### Running Tests

Tests are managed with `pytest`. Use `uv` to run them in the correct environment:

```bash
uv run pytest
```

### Code Quality

This project uses `ruff` for linting and formatting:

```bash
# Check for linting issues
uv run ruff check

# Format code
uv run ruff format
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

## License

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