# Flask-WooCommerce

[![CI](https://forgejo.atelier-26.net/quentin.boudinel/Flask-WooCommerce/badges/workflows/ci.yml/badge.svg)](https://forgejo.atelier-26.net/quentin.boudinel/Flask-WooCommerce/actions)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

A Flask extension that integrates the [WooCommerce REST API](https://woocommerce.github.io/woocommerce-rest-api-docs/) into your application.

## Installation

```bash
pip install flask-woocommerce
```

## Usage

### Configuration

Add your WooCommerce credentials to the Flask app config:

```python
app.config["WOOCOMMERCE"] = {
    "url": "https://your-store.com",
    "consumer_key": "ck_...",
    "consumer_secret": "cs_...",
}
```

#### Optional settings

| Key | Type | Description |
|-----|------|-------------|
| `wp_api` | `bool` | Enable the WP REST API integration |
| `version` | `str` | API version (e.g. `wc/v3`) |
| `timeout` | `float` | Request timeout in seconds |
| `verify_ssl` | `bool` | Verify SSL certificates |
| `query_string_auth` | `bool` | Use query string auth instead of HTTP Basic |
| `user_agent` | `str` | Custom `User-Agent` header value |

### Initialisation

Eager:

```python
from flask import Flask
from flask_woocommerce import WooCommerce

app = Flask(__name__)
app.config["WOOCOMMERCE"] = { ... }
wc = WooCommerce(app)
```

Deferred (application factory pattern):

```python
wc = WooCommerce()

def create_app():
    app = Flask(__name__)
    app.config["WOOCOMMERCE"] = { ... }
    wc.init_app(app)
    return app
```

### Making requests

Access the underlying API client via the `client` property:

```python
# Get all products
response = wc.client.get("products")

# Create a product
response = wc.client.post("products", {"name": "New Product", "regular_price": "9.99"})

# Update a product
response = wc.client.put("products/123", {"regular_price": "12.99"})

# Delete a product
response = wc.client.delete("products/123")
```

### Multiple stores

To connect to more than one WooCommerce store, use a dict-of-dicts config:

```python
app.config["WOOCOMMERCE"] = {
    "default": {
        "url": "https://main-store.com",
        "consumer_key": "ck_...",
        "consumer_secret": "cs_...",
    },
    "wholesale": {
        "url": "https://wholesale-store.com",
        "consumer_key": "ck_...",
        "consumer_secret": "cs_...",
    },
}

wc = WooCommerce(app)

# Access clients by name
main_products = wc.client.get("products")           # "default" client
wholesale_products = wc.clients["wholesale"].get("products")
```

### Logging

Flask-WooCommerce uses Python's standard logging module to provide visibility into extension initialization and configuration. This can be helpful for debugging configuration issues.

Enable debug logging to see detailed information:

```python
import logging

# Enable debug logging for Flask-WooCommerce
logging.getLogger('flask_woocommerce').setLevel(logging.DEBUG)

# Or configure via Flask's logging
app.logger.setLevel(logging.DEBUG)
```

Log levels used:
- **DEBUG**: Configuration validation, client creation details
- **INFO**: Extension initialization summary
- **ERROR**: Configuration errors with full traceback

**Security note**: Sensitive credentials (consumer_key, consumer_secret) are automatically masked in debug logs.

## Example Application

A complete example application is available in the [`example/`](example/) directory. It demonstrates:

- Basic setup and configuration
- Making API requests
- Error handling
- Multiple endpoint examples

See [example/README.md](example/README.md) for setup instructions.

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT
