Metadata-Version: 2.4
Name: bakong-khqr-image
Version: 0.1.3
Summary: Generate styled Bakong KHQR card images with correct USD/KHR amount formatting.
Author-email: Virackbot <virackbot@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Virackbot/bakong-khqr-image
Project-URL: Repository, https://github.com/Virackbot/bakong-khqr-image
Project-URL: Bug Tracker, https://github.com/Virackbot/bakong-khqr-image/issues
Keywords: bakong,khqr,cambodia,qrcode,payment,emv
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=10.0
Requires-Dist: qrcode[pil]>=7.4
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Dynamic: license-file

# bakong-khqr-image

[![PyPI version](https://img.shields.io/pypi/v/bakong-khqr-image.svg)](https://pypi.org/project/bakong-khqr-image/)
[![Python versions](https://img.shields.io/pypi/pyversions/bakong-khqr-image.svg)](https://pypi.org/project/bakong-khqr-image/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Generate **styled Bakong KHQR card images** that match the official NBC design — with correct USD and KHR amount formatting.

> Built from production experience: the official `bakong-khqr` library formats USD amounts with a **comma** (`0,01 USD`) instead of a **period** (`0.01 USD`). This library fixes that and ships a clean, standalone implementation.

---

## Features

- ✅ EMV-compliant KHQR payload generation (no external bakong dependency)
- ✅ Correct amount formatting — `1,234.56` USD · `4,000` KHR
- ✅ Styled 300 × 450 px card (Bakong red header, merchant info, dashed separator, rounded corners)
- ✅ Bundled assets — works out of the box, no manual font/icon setup
- ✅ Multiple export formats: PNG · JPEG · WebP · bytes · Base64 · data URI
- ✅ Static (open-amount) and dynamic QR code support
- ✅ Typed, documented, tested

---

## Installation

```bash
pip install bakong-khqr-image
```

Dependencies (`Pillow` and `qrcode`) are installed automatically.

---

## Quick Start

```python
from bakong_khqr_image import KHQRImage

# Create one instance per merchant — reuse it for every payment
khqr = KHQRImage(
    bakong_account_id="yourname@aclb",
    merchant_name="My Coffee Shop",
    merchant_city="Phnom Penh",   # optional, default "Phnom Penh"
    currency="USD",               # optional, default "USD"
)

# Generate a styled QR card image
result = khqr.generate_image(amount=2.50)

# Save as PNG
result.save_png("payment_qr.png")

# Or get bytes / Base64 / data URI for web / API responses
png_bytes = result.to_bytes()
b64       = result.to_base64()
data_uri  = result.to_data_uri()
```

---

## API Reference

### `KHQRImage`

```python
KHQRImage(
    bakong_account_id: str,
    merchant_name: str,
    merchant_city: str = "Phnom Penh",
    currency: str = "USD",           # "USD" or "KHR"
)
```

#### `generate_image(amount, *, bill_number, store_label, terminal_label, mobile_number, static) → QRImageResult`

Renders the full styled card image.

| Parameter        | Type    | Description                                       |
|------------------|---------|---------------------------------------------------|
| `amount`         | `float` | Transaction amount. `0` = open-amount / static QR |
| `bill_number`    | `str`   | Unique reference ID (auto-generated if omitted)   |
| `store_label`    | `str`   | Store label shown in the Bakong app               |
| `terminal_label` | `str`   | Terminal identifier                               |
| `mobile_number`  | `str`   | Merchant phone number                             |
| `static`         | `bool`  | `True` → static QR (no amount in payload)        |

#### `generate_payload(amount, *, ...) → (payload, bill_number)`

Returns only the raw EMV KHQR string — useful for custom renderers or the Bakong payment-verification API.

```python
payload, ref_id = khqr.generate_payload(amount=5.00)
md5_hash = KHQRImage.md5(payload)   # pass to Bakong API to check payment status
```

#### `KHQRImage.md5(payload) → str`

Computes the MD5 hash of a payload string required by the Bakong transaction-check API.

---

### `QRImageResult`

| Method              | Returns  | Description                              |
|---------------------|----------|------------------------------------------|
| `save_png(path)`    | `str`    | Save PNG, returns absolute path          |
| `save_jpeg(path)`   | `str`    | Save JPEG, returns absolute path         |
| `save_webp(path)`   | `str`    | Save lossless WebP, returns absolute path|
| `to_bytes()`        | `bytes`  | PNG-encoded bytes                        |
| `to_base64()`       | `str`    | Base64-encoded PNG string                |
| `to_data_uri()`     | `str`    | `data:image/png;base64,…` URI            |
| `.image`            | `PIL.Image` | Raw PIL Image for custom processing   |

---

## Examples

### KHR currency

```python
from bakong_khqr_image import KHQRImage

khqr = KHQRImage(
    bakong_account_id="yourname@aclb",
    merchant_name="ហាងកាហ្វេ",
    currency="KHR",
)
result = khqr.generate_image(amount=4_000)
result.save_png("payment_khr.png")
```

### Static (open-amount) QR

```python
result = khqr.generate_image(amount=0, static=True)
result.save_png("static_qr.png")
```

### Web / API response

```python
result = khqr.generate_image(amount=1.50)
# Return as JSON
import json
response = {"qr_image": result.to_data_uri()}
```

### Access the raw PIL image

```python
result = khqr.generate_image(amount=2.50)
pil_image = result.image          # PIL.Image.Image
pil_image.show()                  # open in system viewer
```

---

## Card Layout

```
┌─────────────────────────────┐  ◥ red fold
│  [KHQR / Bakong logo]       │  ← red header (60 px)
│                             │
│  Merchant Name              │
│  2.50 USD                   │
│ - - - - - - - - - - - - - - │  ← dashed separator
│                             │
│    ┌───────────────────┐    │
│    │                   │    │
│    │    QR Code        │    │
│    │      [💲]         │    │  ← currency icon overlay
│    │                   │    │
│    └───────────────────┘    │
│                             │
└─────────────────────────────┘
         300 × 450 px
```

---
## Sample image
![USD QR sample](https://i.imgur.com/cabzQmf.png)
![KHR QR sample](https://i.imgur.com/3nssiDC.png)

## Running Tests

```bash
pip install -e ".[dev]"
pytest
```

---

## Publishing to PyPI

```bash
pip install build twine
python -m build
twine upload dist/*
```

---

## License

[MIT](LICENSE) © 2026 Virackbot
