Metadata-Version: 2.4
Name: mpesa-wrapper
Version: 1.0.0
Summary: Production-ready M-Pesa (Daraja API) SDK for Python
Author: Kimani
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: python-dotenv
Requires-Dist: tenacity
Requires-Dist: pydantic>=2.0
Requires-Dist: cryptography>=40.0
Requires-Dist: httpx
Provides-Extra: web
Requires-Dist: fastapi; extra == "web"
Requires-Dist: uvicorn; extra == "web"
Requires-Dist: jinja2; extra == "web"
Requires-Dist: python-multipart; extra == "web"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-mock; extra == "test"
Requires-Dist: pytest-asyncio; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs; extra == "docs"
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: mkdocstrings[python]; extra == "docs"
Dynamic: license-file
Dynamic: requires-python

# 💳 mpesa-wrapper

Production-ready M-Pesa (Daraja API) SDK for Python.

A type-safe, robust, and modern wrapper for Safaricom's M-Pesa APIs, designed for both synchronous and asynchronous applications.

## 🚀 Features

- **Stripe-level DX**: Type-safe responses with Pydantic (full autocomplete).
- **Production-First**: Automatic phone number masking in logs, RSA security credential generation, and config protection.
- **Resilient**: Built-in exponential backoff retries for network and server errors.
- **Idempotency**: Automatic `X-Idempotency-Key` management for critical transactions.
- **Async Support**: Native `AsyncMpesaClient` for FastAPI and other async frameworks.
- **Comprehensive**: Supports STK Push, B2C, C2B, Reversal, Transaction Status, and Account Balance.

## 📦 Install

```bash
pip install mpesa-wrapper
```

For web-related features (FastAPI demo):
```bash
pip install "mpesa-wrapper[web]"
```

## ⚡ Quick Start

```python
from mpesa_wrapper import MpesaClient

# Initialize from environment variables
client = MpesaClient.from_env()

# STK Push (Lipa Na M-PESA Online)
response = client.stk_push(
    phone_number="254712345678",
    amount=1,
    account_reference="Order123",
    transaction_desc="Payment for shoes"
)

# Type-safe access with autocomplete!
if response.response_code == "0":
    print(f"Success! CheckoutID: {response.checkout_request_id}")
```

## 🔐 Configuration

Create a `.env` file based on `.env.example`:

```env
MPESA_CONSUMER_KEY=your_key
MPESA_CONSUMER_SECRET=your_secret
MPESA_SHORTCODE=174379
MPESA_PASSKEY=your_passkey
MPESA_ENV=sandbox

# Required for B2C, Reversal, Balance, Status
MPESA_INITIATOR_NAME=testapi
MPESA_INITIATOR_PASSWORD=your_password
MPESA_CERTIFICATE_PATH=./path/to/cert.cer
MPESA_RESULT_URL=https://your-domain.com/result
MPESA_TIMEOUT_URL=https://your-domain.com/timeout
```

## 🐳 Running the Demo (Docker)

```bash
docker build -t mpesa-demo .
docker run -p 8000:8000 --env-file .env mpesa-demo
```

## 📄 License

Distributed under the MIT License. See `LICENSE` for more information.
