Metadata-Version: 2.4
Name: famapp-gateway
Version: 0.1.0
Summary: The main payment gateway orchestrator for FamApp payments, providing a self-hosted alternative to Razorpay.
Author: iy3k
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: famapp-mailparser>=0.1.0
Requires-Dist: famapp-qr>=0.1.0
Requires-Dist: famapp-transac-log>=0.1.0
Dynamic: license-file

<div align="center">
  <img src="https://capsule-render.vercel.app/api?type=waving&color=f72585&height=200&section=header&text=famapp-gateway&fontSize=40&fontColor=fff&animation=twinkling&fontAlignY=35"/>
  
  <br/>
  
  <img src="https://readme-typing-svg.herokuapp.com?font=Fira+Code&size=18&duration=3000&pause=1000&color=F72585&center=true&vCenter=true&width=500&lines=Razorpay+Alternative+for+FamPay;Lightweight+%26+Database-Optional;Secure+Polling+%26+Replay+Protection" alt="Typing SVG" />
  
  <br/>

[![PyPI Version](https://img.shields.io/badge/pypi-v0.1.0-blueviolet?style=for-the-badge&logo=pypi)](https://pypi.org/)
[![Python Version](https://img.shields.io/badge/python-3.8+-brightgreen?style=for-the-badge&logo=python)](https://python.org/)
[![License](https://img.shields.io/badge/license-MIT-green?style=for-the-badge)](https://opensource.org/licenses/MIT)

<br/>
<img src="../../assets/gateway_banner.png" width="100%" alt="famapp-gateway Illustration" />

</div>

---

### `>_ root@famapp:~/gateway# ./verify_order.sh`

```text
User                      Application               famapp-gateway             Gmail
 │                             │                          │                      │
 ├─► Select Plan               │                          │                      │
 │                             ├─► create_order() ───────►│                      │
 │                             │◄─ [QR, TN Note] ─────────┤                      │
 │◄─ Show checkout ────────────┤                          │                      │
 │                             │                          │                      │
 ⏰ Start 5-Minute Polling Queue (verify_order)           │                      │
 │                             ├─► poll_async() ─────────►├─► fetch_recent() ───►│
 │                             │                          │◄─ [Parsed emails] ───┤
 │                             │                          ├─► verify & save ────┐│
 │                             │                          │◄── [Success] ───────┘│
 │                             │◄─ {"verified": true} ────┤                      │
 │◄─ Payment Success ──────────┤                          │                      │
```

---

### `>_ root@famapp:~/gateway# ./verify_manual_fallback.sh`

```text
User                      Application               famapp-gateway             Gmail
 │                             │                          │                      │
 ├─► Enters UTR / Txn ID ──────┤                          │                      │
 │                             ├─► verify_manual(ref) ───►├─► fetch_recent() ───►│
 │                             │                          │◄─ [Parsed emails] ───┤
 │                             │                          ├─► Match ref & save ─┐│
 │                             │                          │◄── [Success] ───────┘│
 │                             │◄─ {"verified": true} ────┤                      │
 │◄─ Payment Success ──────────┤                          │                      │
```

---

### `>_ root@famapp:~/gateway# cat apis.txt`

#### 1. Initialize Gateway
```python
from famapp_gateway import FamAppGateway

gateway = FamAppGateway(
    gmail_user="your_email@gmail.com",
    gmail_password="your_app_password",
    storage_type="sqlite",
    storage_config={"db_path": "payments.db"}
)
```

#### 2. Generate Order (QR & Custom Note)
```python
order = gateway.create_order(
    upi_id="example@fam",
    amount=16.00,
    name="Aura Zod"
)

print(order["note"])      # Unique note (e.g. TN8D4F9A)
print(order["qr_image"])  # Base64 QR Image string
```

#### 3. Asynchronous Verification Polling (5-Min Timeout)
```python
result = await gateway.verify_order_poll_async(
    amount=16.00,
    note=order["note"]
)

if result["verified"]:
    print(f"Success! Received ₹{result['amount']} from {result['sender_name']}")
```

#### 4. Manual Fallback Verification
```python
result = gateway.verify_manual_reference(
    amount=16.00,
    reference_id="210766238795" # User inputs UTR or FamApp Transaction ID
)

if result["verified"]:
    print("Success! Manual transaction verified.")
```

---

### Open Source Contribution

This project is fully open source. We encourage and welcome contributions from the community to help improve, optimize, and extend the ecosystem. Feel free to open issues or submit pull requests!

## 🪪 License
This project is licensed under the [MIT License](https://opensource.org/licenses/MIT). See the [LICENSE](https://github.com/AuraZod/Quo/blob/main/LICENSE) file for details.

---

### Contributors 👥
<a href="https://github.com/AuraZod/famapp-gateway/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=AuraZod/famapp-gateway" />
</a>
