keble-payment 2.4.1__py3-none-any.whl

keble_payment/__init__.py

@@ -0,0 +1,5 @@
+from . import stripe
+from .alipay import *  # noqa: F403
+from .main import *  # noqa: F403
+from .protocols import CouponAttributionProviderProtocol
+from .schemas import *  # noqa: F403

keble_payment/alipay/__init__.py

@@ -0,0 +1 @@
+from .client import AlipayClient, AlipayPaymentSuccessNotification

keble_payment/alipay/client.py

@@ -0,0 +1,199 @@
+import logging
+from typing import Optional
+
+import alipay
+import keble_exceptions
+from keble_helpers import ObjectId
+from pydantic import BaseModel
+
+from ..utils import std_money_int_to_float
+
+logger = logging.getLogger(__name__)
+
+
+class AlipayPaymentSuccessNotification(BaseModel):
+    raw_data: dict
+    money: int
+    app_id: Optional[str] = None
+    trade_no: str
+
+
+class AlipayClient:
+    def __init__(
+        self,
+        *,
+        app_private_key_string: str,
+        alipay_public_key_string: str,
+        app_id: str,
+        app_notify_url: str,
+        sign_type: str = "RSA2",
+        debug: bool = False,
+        dev_test: bool = False,
+    ):
+        self._app_id = app_id
+        self._app_notify_url = app_notify_url
+        self._dev_test = dev_test
+        self._ac = None
+        if app_private_key_string != "" and alipay_public_key_string != "":
+            self._ac = alipay.AliPay(
+                appid=app_id,
+                app_notify_url=app_notify_url,  # 默认回调url
+                app_private_key_string=app_private_key_string,
+                # 支付宝的公钥，验证支付宝回传消息使用，不是你自己的公钥,
+                alipay_public_key_string=alipay_public_key_string,
+                sign_type=sign_type,  # RSA 或者 RSA2
+                debug=debug,  # 默认False
+            )
+        elif not dev_test:
+            raise keble_exceptions.ClientSideInvalidParams(
+                invalid_params="alipay_key_material",
+                expected="Alipay private and public key strings",
+                but_got="missing",
+                alert_admin=True,
+                admin_note="AlipayClient requires key material outside dev_test mode.",
+            )
+
+    def _require_alipay_client(self):
+        """Return the SDK client for methods that call real Alipay APIs."""
+
+        if self._ac is None:
+            raise keble_exceptions.ClientSideInvalidParams(
+                invalid_params="alipay_key_material",
+                expected="Alipay private and public key strings",
+                but_got="missing",
+                alert_admin=True,
+                admin_note="This Alipay operation requires key-backed SDK client setup.",
+            )
+        return self._ac
+
+    def transfer(
+        self,
+        *,
+        transfer_id: str,
+        to_alipay_account: str,  # email
+        money: int,
+        payee_real_name: str,
+        remark: str,
+        payer_name: str,
+    ) -> dict:
+        """fund transaction in alipay"""
+
+        to_alipay_account = str(to_alipay_account)
+        if (
+            len(to_alipay_account) == 16
+            and to_alipay_account[:4] == "2088"
+            and "@" not in to_alipay_account
+        ):
+            # https://opendocs.alipay.com/open/309/alipay.fund.trans.toaccount.transfer
+            payee_type = "ALIPAY_USERID"
+        else:
+            payee_type = "ALIPAY_LOGONID"
+        adjusted_money_amount = std_money_int_to_float(money)
+        if adjusted_money_amount >= 4000:
+            raise keble_exceptions.ClientSideInvalidParams(
+                invalid_params="money",
+                expected="< 4000",
+                but_got=str(adjusted_money_amount),
+                alert_admin=True,
+                admin_note="Exceeded maximum threshold 4000 for Alipay transfer",
+            )
+        # fund_trans_id = datetime.now().strftime("%Y%m%d%H%M%S")
+
+        try:
+            result = (
+                self._require_alipay_client().api_alipay_fund_trans_toaccount_transfer(
+                    out_biz_no=transfer_id,
+                    payee_type=payee_type,
+                    payee_account=to_alipay_account,
+                    amount=adjusted_money_amount,
+                    payee_real_name=payee_real_name,  # 收款方姓名（可选，若不匹配则转账失败）
+                    remark=remark,  # 转账备注
+                    payer_show_name=payer_name,  # 付款方姓名
+                )
+            )
+            if "code" in result and "msg" in result:
+                if (
+                    str(result["code"]) == "10000"
+                    and result["msg"].lower() == "success"
+                ):
+                    return result
+        except Exception as e:
+            logger.error(
+                "[Payment] Alipay Error. Error return from alipay transfer API, by python sdk: {}".format(
+                    e
+                )
+            )
+            raise e
+        raise keble_exceptions.RequestFailure(
+            admin_note=f"Alipay transaction issued. But unable to identify result as success. See result: {result}",
+            function_identifier="alipay.transfer",
+            alert_admin=True,
+        )
+
+    def parse_payment_success_notification(
+        self, data: dict
+    ) -> Optional[AlipayPaymentSuccessNotification]:
+        # Fetch remote order data status directly to validate the payment status
+        if data["trade_status"] in ["TRADE_FINISHED", "TRADE_SUCCESS"]:
+            retried = 0
+            max_retried = 10
+            while retried < max_retried:
+                try:
+                    if self._dev_test:
+                        # use the raw data, do not fetch from alipay
+                        result = data
+                    else:
+                        result = self._require_alipay_client().api_alipay_trade_query(
+                            out_trade_no=data["out_trade_no"]
+                        )
+                    logger.info(
+                        f"[Payment] Alipay check trade query. Retry {retried}. Result: {result}"
+                    )
+                    if result["trade_status"] in ["TRADE_FINISHED", "TRADE_SUCCESS"]:
+                        # receipt_amount = float(data["receipt_amount"])
+                        if "total_amount" in data:
+                            # prioritize total_amount key
+                            # base on alipay doc, total_amount is the actual value set by merchant
+                            receipt_amount = float(data["total_amount"])
+                        elif "receipt_amount" in data:
+                            # receipt amount key can be misleading, therefore make it as a fallback
+                            receipt_amount = float(data["receipt_amount"])
+                        money_int = int(receipt_amount * 100)
+                        return AlipayPaymentSuccessNotification(
+                            raw_data=data,
+                            money=money_int,
+                            app_id=data.get("app_id"),
+                            trade_no=data["trade_no"],
+                        )
+                except Exception as e:
+                    logger.info(f"[Payment] Alipay check trade query. Exception: {e}")
+                retried += 1
+        return None
+
+    def build_alipay_wap_payment_url(
+        self,
+        *,
+        payment_id: ObjectId,
+        money: int,
+        subject: str,
+        return_url: str,
+        notify_url: str,
+        hb_fq_num=None,
+        hb_fq_seller_percent: float = 0,
+    ) -> str:
+        if hb_fq_num is None or hb_fq_num == 1:
+            order_string = self._require_alipay_client().api_alipay_trade_wap_pay(
+                out_trade_no=str(payment_id),
+                total_amount=std_money_int_to_float(money),
+                subject=subject,
+                return_url=return_url,
+                notify_url=notify_url,  # 可选, 不填则使用默认notify url
+            )
+        else:
+            raise keble_exceptions.UnhandledScenarioOrCase(
+                unhandled_case=f"hb_fq_num={hb_fq_num}",
+                alert_admin=True,
+                admin_note=f"Missing ALIPAY PID for this hb_fq_num {hb_fq_num}",
+            )
+
+        return "https://openapi.alipay.com/gateway.do?" + order_string

keble_payment/crud/__init__.py

@@ -0,0 +1,14 @@
+from .alipay import CRUDAlipay
+from .bank_transaction import CRUDBankTransaction
+from .coupon import CRUDCoupon
+from .coupon_history import CRUDCouponHistory
+from .order import CRUDOrder
+from .payment import CRUDPayment
+from .stripe_card import CRUDStripeCard
+from .stripe_checkout_session import CRUDStripeCheckoutSession
+from .stripe_customer import CRUDStripeCustomer
+from .stripe_payment_intent import CRUDStripePaymentIntent
+from .stripe_payment_method import CRUDStripePaymentMethod
+from .stripe_subscription import CRUDStripeSubscription
+from .stripe_invoice import CRUDStripeInvoice
+from .paypal_payout import CRUDPayPalPayoutBatch, CRUDPayPalPayoutItem

keble_payment/crud/alipay.py

@@ -0,0 +1,27 @@
+from typing import Optional
+
+from keble_db import MongoCRUDBase, QueryBase
+from keble_helpers import ObjectId
+from motor.motor_asyncio import AsyncIOMotorClient
+from pymongo import ASCENDING, IndexModel
+
+from keble_payment import schemas
+
+
+class CRUDAlipay(MongoCRUDBase[schemas.AlipayMongoObject]):
+    async def aensure_indexes(self, m: AsyncIOMotorClient) -> None:
+        """Create Mongo indexes for Alipay payment side-table reads.
+
+        Step by step:
+        1. select the Alipay side-table collection;
+        2. index payment-id lookup filters.
+        """
+
+        await m[self.database][self.collection].create_indexes(
+            [IndexModel([("payment", ASCENDING)], name="payment_idx")]
+        )
+
+    async def aget_by_payment(
+        self, m: AsyncIOMotorClient, *, payment_id: ObjectId
+    ) -> Optional[schemas.AlipayMongoObject]:
+        return await self.afirst(m, query=QueryBase(filters={"payment": payment_id}))

keble_payment/crud/bank_transaction.py

@@ -0,0 +1,27 @@
+from typing import Optional
+
+from keble_db import MongoCRUDBase, QueryBase
+from keble_helpers import ObjectId
+from motor.motor_asyncio import AsyncIOMotorClient
+from pymongo import ASCENDING, IndexModel
+
+from keble_payment import schemas
+
+
+class CRUDBankTransaction(MongoCRUDBase[schemas.BankTransactionMongoObject]):
+    async def aensure_indexes(self, m: AsyncIOMotorClient) -> None:
+        """Create Mongo indexes for bank-transaction payment reads.
+
+        Step by step:
+        1. select the bank transaction side-table collection;
+        2. index payment-id lookup filters.
+        """
+
+        await m[self.database][self.collection].create_indexes(
+            [IndexModel([("payment", ASCENDING)], name="payment_idx")]
+        )
+
+    async def aget_by_payment(
+        self, m: AsyncIOMotorClient, *, payment_id: ObjectId
+    ) -> Optional[schemas.BankTransactionMongoObject]:
+        return await self.afirst(m, query=QueryBase(filters={"payment": payment_id}))

keble_payment/crud/coupon.py

@@ -0,0 +1,254 @@
+import datetime
+from typing import Optional
+
+import keble_exceptions
+from bson import ObjectId
+from keble_db import MongoCRUDBase, QueryBase
+from keble_helpers import Currency, Marketplace
+from motor.motor_asyncio import AsyncIOMotorClient
+from pymongo import ASCENDING, DESCENDING, TEXT, IndexModel
+
+from keble_payment import schemas
+
+
+class CRUDCoupon(MongoCRUDBase[schemas.CouponMongoObject]):
+    async def aensure_indexes(self, m: AsyncIOMotorClient) -> None:
+        """Create Mongo indexes for coupon code and expiry reads.
+
+        Step by step:
+        1. select the CRUD-owned coupon collection;
+        2. index active coupon lookups by code and expiry timestamp.
+        """
+
+        await m[self.database][self.collection].create_indexes(
+            [
+                IndexModel(
+                    [("code", ASCENDING), ("expired_at", ASCENDING)],
+                    name="code_expired_at_idx",
+                ),
+                IndexModel(
+                    [
+                        ("attribution_status", ASCENDING),
+                        ("created", DESCENDING),
+                        ("_id", DESCENDING),
+                    ],
+                    name="attribution_status_created_desc_idx",
+                ),
+                IndexModel(
+                    [("created", DESCENDING), ("_id", DESCENDING)],
+                    name="created_desc_idx",
+                ),
+                IndexModel(
+                    [("code", ASCENDING), ("_id", ASCENDING)],
+                    name="code_id_idx",
+                ),
+                IndexModel(
+                    [("consumed", DESCENDING), ("_id", DESCENDING)],
+                    name="consumed_desc_idx",
+                ),
+                IndexModel(
+                    [("expired_at", DESCENDING), ("_id", DESCENDING)],
+                    name="expired_at_desc_idx",
+                ),
+                IndexModel(
+                    [("code", TEXT), ("referrer", TEXT), ("tag_keys", TEXT)],
+                    name="coupon_search_text_idx",
+                ),
+            ]
+        )
+
+    async def amigrate_attribution_status(self, m: AsyncIOMotorClient) -> None:
+        """Backfill the indexed assignment status for legacy coupon documents.
+
+        Steps:
+        1. mark documents with at least one tag key as ASSIGNED;
+        2. mark missing/empty tag arrays as UNASSIGNED;
+        3. update only mismatched rows so startup remains idempotent.
+
+        Side effects if changes:
+        - admin unassigned pagination and batch proposal scans use this field;
+        - backend startup invokes this before serving coupon reads.
+        """
+
+        collection = m[self.database][self.collection]
+        await collection.update_many(
+            {
+                "tag_keys.0": {"$exists": True},
+                "attribution_status": {
+                    "$ne": schemas.CouponAttributionStatus.ASSIGNED.value
+                },
+            },
+            {
+                "$set": {
+                    "attribution_status": schemas.CouponAttributionStatus.ASSIGNED.value
+                }
+            },
+        )
+        await collection.update_many(
+            {
+                "tag_keys.0": {"$exists": False},
+                "attribution_status": {
+                    "$ne": schemas.CouponAttributionStatus.UNASSIGNED.value
+                },
+            },
+            {
+                "$set": {
+                    "attribution_status": schemas.CouponAttributionStatus.UNASSIGNED.value
+                }
+            },
+        )
+
+    async def alist_page(
+        self,
+        m: AsyncIOMotorClient,
+        *,
+        query: schemas.CouponListQuery,
+    ) -> schemas.CouponPage:
+        """List coupons through the canonical server-side filtered query.
+
+        Collection/query/index contract:
+        - collection: this CRUD's coupon collection;
+        - equality filter: ``attribution_status``;
+        - optional filters: text-indexed code/referrer/tag search and expiry;
+        - sort: requested supported field plus ``_id`` tie-breaker;
+        - indexes: ``attribution_status_created_desc_idx`` for review queues and
+          ``created_desc_idx`` plus explicit code/consumed/expiry sort indexes,
+          and ``coupon_search_text_idx`` for admin search.
+
+        Side effects if changes:
+        - backend ``GET /api/v3/admin/coupons/list`` exposes this page;
+        - frontend admin pagination must mirror its count/sort semantics.
+        """
+
+        filters: dict = {}
+        if query.attribution_status is not None:
+            filters["attribution_status"] = query.attribution_status.value
+        if query.hide_expired:
+            filters["$or"] = [
+                {"expired_at": None},
+                {"expired_at": {"$gte": datetime.datetime.now(datetime.UTC)}},
+            ]
+        if query.search is not None and query.search.strip():
+            filters["$text"] = {"$search": query.search.strip()}
+
+        sort_fields = {
+            schemas.CouponListSortBy.CREATED: "created",
+            schemas.CouponListSortBy.CODE: "code",
+            schemas.CouponListSortBy.CONSUMED: "consumed",
+            schemas.CouponListSortBy.EXPIRED_AT: "expired_at",
+        }
+        direction = (
+            ASCENDING
+            if query.sort_direction is schemas.CouponListSortDirection.ASC
+            else DESCENDING
+        )
+        collection = m[self.database][self.collection]
+        total = await collection.count_documents(filters)
+        cursor = (
+            collection.find(filters)
+            .sort([(sort_fields[query.sort_by], direction), ("_id", direction)])
+            .skip(query.offset)
+            .limit(query.limit)
+        )
+        items = [self._to_model(document) async for document in cursor]
+        return schemas.CouponPage(
+            items=items,
+            total=total,
+            offset=query.offset,
+            limit=query.limit,
+        )
+
+    async def aget_coupon(
+        self,
+        m: AsyncIOMotorClient,
+        *,
+        code: Optional[str] = None,
+        _id: Optional[str | ObjectId] = None,
+    ):
+        if code is None and _id is None:
+            raise keble_exceptions.ServerSideMissingParams(
+                missing_params="code or _id",
+                alert_admin=True,
+                admin_note="You must provide either code or _id parameter to get_coupon",
+            )
+        return await self.afirst(
+            m,
+            query=QueryBase(
+                filters={
+                    "$or": [
+                        {"code": code},
+                        {"_id": ObjectId(_id) if _id is not None else _id},
+                    ],
+                }
+            ),
+        )
+
+    async def acan_create_code(
+        self,
+        m: AsyncIOMotorClient,
+        *,
+        code: str,
+    ) -> bool:
+        # ensure there are no same consumable coupon for this code
+        exp_or = [
+            {"expired_at": {"$eq": None}},
+            {"expired_at": {"$gte": datetime.datetime.now()}},
+        ]
+        _filter = {"code": code, "$or": exp_or}
+        coupon = await self.afirst(m, query=QueryBase(filters=_filter))
+        # if coupon is None and coupon is exhausted at the moment
+        return coupon is None or coupon.exhausted
+
+    async def aget_consumable_coupon(
+        self,
+        m: AsyncIOMotorClient,
+        *,
+        code: Optional[str] = None,
+        coupon_id: Optional[ObjectId] = None,
+        marketplace: Marketplace,
+        currency: Currency,
+    ):
+        exp_or = [
+            {"expired_at": {"$eq": None}},
+            {"expired_at": {"$gte": datetime.datetime.now()}},
+        ]
+        mkt_or = [{"marketplaces": {"$eq": None}}, {"marketplaces": marketplace}]
+        cur_or = [{"currencies": {"$eq": None}}, {"currencies": currency}]
+        _filter = {
+            "$and": [
+                {
+                    "$or": [
+                        {"$and": [{"code": code}, {"code": {"$ne": None}}]},
+                        {"_id": coupon_id},
+                    ]
+                },
+                {"$or": cur_or},
+                {"$or": mkt_or},
+                {"$or": exp_or},
+            ]
+        }
+        coupon = await self.afirst(m, query=QueryBase(filters=_filter))
+        if coupon is None or coupon.exhausted:
+            return None
+        return coupon
+
+    async def aincrement_coupon_usage(
+        self,
+        m: AsyncIOMotorClient,
+        *,
+        coupon_id: ObjectId,
+        increment: int = 1,
+    ):
+        latest_coupon = await self.afirst_by_id(m, _id=coupon_id)
+        if latest_coupon is None:
+            raise keble_exceptions.ObjectNotFound(
+                object_name="coupon",
+                id=str(coupon_id),
+                alert_admin=True,
+                admin_note=f"Coupon with id {coupon_id} not found when incrementing usage",
+            )
+        await self.aupdate(
+            m,
+            _id=latest_coupon.id,
+            obj_in={"consumed": latest_coupon.consumed + increment},
+        )