Metadata-Version: 2.4
Name: poolak
Version: 0.1.0b1
Summary: Python SDK for Poolak Payment and SMS Transaction Matching Engine
Project-URL: Homepage, https://github.com/nyxon-tech/poolak-sdk
Project-URL: Repository, https://github.com/nyxon-tech/poolak-sdk
Project-URL: Bug Tracker, https://github.com/nyxon-tech/poolak-sdk/issues
Author-email: Nyxon Team <poolak.info@nyxon.ir>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: all
Requires-Dist: fastapi>=0.100.0; extra == 'all'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
Description-Content-Type: text/markdown

# Poolak SDK 🪙

کتابخانه رسمی پایتون برای تعامل با درگاه خدمات پرداخت و موتور تطبیق هوشمند تراکنش‌های **پولک (Poolak)**. 

این کیت توسعه نرم‌افزار (SDK) به شما اجازه می‌دهد تا به سادگی تراکنش‌های مالی را در پروژه‌های خود (نظیر ربات‌های تلگرامی، سیستم‌های مالی و وب‌سایت‌ها) ثبت، پیگیری و از طریق استریم زنده یا روترهای وب‌هوک هوشمند پایش کنید.

---

## قابلیت‌های برجسته

* **کلاینت‌های همگام و ناهمگام (Sync/Async):** پشتیبانی کامل از برنامه‌نویسی غیرهمزمان با `AsyncPoolak` و همزمان با `Poolak` بر پایه کتابخانه قدرتمند `httpx`.
* **مدیریت خودکار ارزها:** تعریف مستقیم مبالغ با کلاس‌های `Toman` یا `Rial` و مدیریت هوشمند تبدیل واحدها قبل از ارسال به درگاه.
* **استریم زنده وضعیت تراکنش‌ها (SSE):** امکان رصد و دریافت آنی وضعیت تراکنش‌ها بدون نیاز به کوئری‌های تکراری (Polling).
* **پلاگین آماده وب‌هوک برای FastAPI:** دارای روتر توکار جهت دریافت امن اعلان‌های وب‌هوک پرداخت همراه با اعتبارسنجی خودکار امضای هَش‌شده (HMAC-SHA256).
* **اعتبارسنجی قوی با Pydantic:** استفاده از Pydantic نسخه ۲ برای مدل‌سازی و بررسی دقیق داده‌ها قبل و بعد از ارسال به سرور.

---

## نصب و راه‌اندازی

شما می‌توانید بسته اصلی کتابخانه را با دستور زیر نصب کنید:

```bash
pip install poolak
```

اگر قصد دارید از افزونه وب‌هوک این کتابخانه برای هماهنگی با فریم‌ورک **FastAPI** استفاده کنید، آن را با دستور زیر نصب نمایید تا ابزارهای موردنیاز FastAPI نیز به طور خودکار دریافت شوند:

```bash
pip install poolak[fastapi]
```

---

## تنظیمات محیطی (Environment Variables)

برای راه‌اندازی آسان و بدون نیاز به پاس دادن توکن‌ها درون کد برنامه‌نویسی، می‌توانید متغیرهای محیطی زیر را تنظیم کنید:

```bash
export POOLAK_BOT_TOKEN="your_bot_token_here"
export POOLAK_PARTNER_TOKEN="your_partner_token_here" # اختیاری
export POOLAK_BASE_URL="https://api.poolak.ir" # اختیاری برای تغییر درگاه سرور
```

---

## شروع سریع (Quick Start)

برای ایجاد تراکنش، به شناسه کارت بانکی فعال خود (`destination_card_id`) نیاز دارید. در ابتدا می‌توانید لیست کارت‌های فعال خود را دریافت کنید:

### ۱. دریافت لیست کارت‌های بانکی فعال

```python
from poolak import Poolak

with Poolak(bot_token="your_bot_token") as client:
    cards = client.get_cards()
    for card in cards:
        print(f"بانک: {card.bank.name} | شماره کارت: {card.card_number} | شناسه کارت: {card.id}")
```

### ۲. ثبت تراکنش به صورت همگام (Synchronous)

```python
from poolak import Poolak, Toman

# ثبت یک تراکنش جدید با واحد تومان
with Poolak(bot_token="your_bot_token") as client:
    try:
        transaction = client.create_transaction(
            order_id="order_10024",
            amount=Toman(10000), # مقداردهی با تومان (به طور خودکار به ریال تبدیل می‌شود)
            destination_card_id="وارد کنید card.id شناسه کارت خود را از بخش قبلی"
        )
        print(f"تراکنش با شناسه {transaction.id} ثبت شد. مبلغ نهایی ریال: {transaction.final_amount}")
    except Exception as e:
        print(f"خطا در ثبت تراکنش: {e}")
```

### ۳. اجرای ناهمگام (Asynchronous)

استفاده از کلاس `AsyncPoolak` به همراه ساختار `async with` برای پروژه‌های ناهمگام (نظیر ربات‌های تلگرامی پیشرفته):

```python
import asyncio
from poolak import AsyncPoolak, Toman

async def main():
    async with AsyncPoolak() as client: # خواندن خودکار توکن از متغیر محیطی
        # ایجاد تراکنش
        transaction = await client.create_transaction(
            order_id="order_10025",
            amount=Toman(5000),
            destination_card_id="8f90b1c0-0000-0000-0000-000000000000"
        )
        print(f"تراکنش ثبت شد: {transaction.id}")

        # بررسی آنی وضعیت تراکنش
        status = await client.check_transaction(transaction_id=transaction.id)
        print(f"وضعیت فعلی: {status.status}")

asyncio.run(main())
```

---

## ردیابی آنی پرداخت‌ها (Real-time Payment Tracking)

یکی از ویژگی‌های قدرتمند سرویس پولک، ردیابی زنده وضعیت تراکنش‌ها بدون ارسال کوئری‌های مکرر به شبکه است. به دو روش می‌توانید منتظر تایید تراکنش بمانید:

### متد معلق‌کننده (Blocking)
این متد تا زمانی که خریدار تراکنش را با موفقیت واریز نکند، برنامه را متوقف نگه می‌دارد (تا سقف زمان مشخص‌شده برای انقضا):

```python
import asyncio
from poolak import AsyncPoolak

async def main():
    async with AsyncPoolak() as client:
        print("در حال انتظار برای پرداخت...")
        status = await client.wait_for_payment(
            transaction_id="8f90b1c0-0000-0000-0000-000000000000",
            timeout=900 # حداکثر زمان انتظار به ثانیه
        )
        print(f"پرداخت با وضعیت خاتمه یافت: {status}")

asyncio.run(main())
```

### استریم زنده رویدادها (Stream)
اگر نیاز دارید تا وضعیت تغییرات را به صورت واکنشی پایش کنید، می‌توانید رویدادها را استریم کنید:

```python
import asyncio
from poolak import AsyncPoolak

async def main():
    async with AsyncPoolak() as client:
        async for event in client.stream_transaction("8f90b1c0-0000-0000-0000-000000000000"):
            print(f"رویداد جدید دریافت شد: {event.status}")

asyncio.run(main())
```

---

## یکپارچه‌سازی وب‌هوک با FastAPI

اگر می‌خواهید اطلاعات پرداخت‌ها را مستقیماً بر روی وب‌سایت خود دریافت کنید، می‌توانید از روتر اختصاصی پولک استفاده کنید. این روتر به طور خودکار صحت امضای ارسالی از سرور پولک را بررسی می‌کند و در صورت صحت، عملیات را در پس‌زمینه اجرا می‌نماید:

```python
from fastapi import FastAPI
from poolak.contrib.fastapi import PoolakWebhookRouter

app = FastAPI()

# تعریف وب‌هوک با کلید رمز وب‌هوک دریافت شده از پنل پولک
webhook_router = PoolakWebhookRouter(webhook_secret="your_webhook_secret_key")

@webhook_router.on_paid()
async def handle_payment_event(payload: dict):
    # این تابع زمانی که واریز تایید شد در پس‌زمینه صدا زده می‌شود
    transaction_id = payload.get("transaction_id")
    order_id = payload.get("order_id")
    final_amount = payload.get("final_amount")
    print(f"پرداخت موفق تایید شد! شماره سفارش: {order_id}، مبلغ: {final_amount}")

# اضافه کردن روتر به اپلیکیشن وب
app.include_router(webhook_router, prefix="/webhooks/poolak")
```

---

## مدیریت خطاها (Error Handling)

خطاهای مربوط به ارتباط با درگاه در استثناهای ساختاریافته دسته‌بندی شده‌اند تا کنترل جریان برنامه آسان‌تر باشد:

```python
from poolak import (
    Poolak, 
    Toman,
    AuthenticationError,
    ValidationError,
    RateLimitError,
    APIResponseError
)

try:
    with Poolak() as client:
        client.create_transaction("order_12", Toman(100), "invalid_card_id")
except AuthenticationError as e:
    print(f"خطای تایید هویت یا توکن نامعتبر: {e}")
except ValidationError as e:
    print(f"خطای اعتبارسنجی مقادیر ارسالی: {e}")
except RateLimitError as e:
    print(f"محدودیت درخواست‌های مکرر به سرور: {e}")
except APIResponseError as e:
    print(f"خطای پاسخ سرور: {e}")
```

---

## سایر متدها و ابزارهای کمکی

علاوه بر متدهای اصلی، SDK قابلیت‌های زیر را نیز ارائه می‌دهد:

* **دریافت وضعیت کیف پول (`get_wallet_status`):** مشاهده موجودی، طرح فعال و تراکنش‌های باقیمانده.
* **تایید دستی تراکنش (`manual_verify`):** امکان تطبیق دستی یک تراکنش تعلیق شده با یک پیامک واریز یتیم (Orphan).
* **دریافت پیامک‌های یتیم (`get_orphans`):** استعلام پیامک‌هایی که به دلیل عدم تطبیق خودکار سیستمی، در دیتابیس یتیم مانده‌اند.

---

## توسعه و اجرای تست‌ها

جهت اجرای آزمون‌های واحد و ارزیابی صحت کارکرد ابزار بر روی سیستم خود، ابتدا نیازمندی‌های توسعه را نصب کرده و دستور زیر را در مسیر ریشه پروژه اجرا کنید:

```bash
pytest
```

---

## لایسنس

این پروژه تحت مجوز [LICENSE](https://github.com/nyxon-tech/poolak-sdk/blob/main/LICENSE) منتشر شده است. استفاده و تغییر در آن برای عموم توسعه‌دهندگان آزاد است.
