sub2api 0.1.1__tar.gz → 0.2.0__tar.gz

{sub2api-0.1.1 → sub2api-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sub2api
-Version: 0.1.1
+Version: 0.2.0
 Summary: Python client for the user-facing API of Sub2API instances
 Author: Eight Labs
 License-Expression: MIT
@@ -31,7 +31,7 @@ Description-Content-Type: text/markdown
 
 `sub2api` is a Python client for the shared user-facing panel API exposed by Sub2API instances. One client object represents one user's in-memory dashboard session. Requests use `curl_cffi` with Chrome browser impersonation by default.
 
-The library targets operations present on standard Sub2API deployments: account balance, platform quotas, usage history and statistics, API keys, groups, subscriptions, announcements, and redemption.
+The library targets operations present on standard Sub2API deployments: account balance, optional payment deposits, payment orders, platform quotas, usage history and statistics, API keys, groups, subscriptions, announcements, and redemption.
 
 ## Install
 
@@ -186,6 +186,39 @@ result = client.redeem("REDEMPTION-CODE")
 redemption_history = client.redeem.history()
 ```
 
+## Deposits and payment
+
+Payment is optional and must be enabled and configured by the instance administrator. Inspect the checkout configuration before offering a deposit:
+
+```python
+checkout = client.payment.checkout_info()
+
+if checkout.methods:
+    order = client.deposit(
+        10,
+        payment_type="stripe",
+        return_url="https://app.example.com/payment/result",
+    )
+    print(order.order_id, order.pay_url, order.qr_code, order.client_secret)
+```
+
+Available payment methods depend on the instance and can include `alipay`, `wxpay`, `stripe`, and `airwallex`. The returned order contains the provider-specific checkout data: a hosted payment URL, QR code, Stripe client secret, or WeChat OAuth/JSAPI payload. Creating the order does not credit the balance; the configured provider must confirm payment before the instance completes the deposit.
+
+Use the payment resource to inspect and manage the order:
+
+```python
+pending = client.payment.get(order.order_id)
+verified = client.payment.verify(order.out_trade_no)
+orders = client.payment.list(status="COMPLETED", order_type="balance")
+client.payment.cancel(order.order_id)
+```
+
+An instance without payment configuration returns its normal typed API error, including `PAYMENT_DISABLED` or `NO_AVAILABLE_INSTANCE`, rather than silently treating a deposit as successful. Public order recovery is also available when a checkout flow has a signed resume token:
+
+```python
+public_order = client.payment.resolve_public(order.resume_token)
+```
+
 ## Fork-specific endpoints
 
 `request()` provides the same authentication, envelope handling, timezone parameter, refresh behavior, and error mapping for relative endpoints that are not part of the stable resource API.

{sub2api-0.1.1 → sub2api-0.2.0}/README.md

@@ -2,7 +2,7 @@
 
 `sub2api` is a Python client for the shared user-facing panel API exposed by Sub2API instances. One client object represents one user's in-memory dashboard session. Requests use `curl_cffi` with Chrome browser impersonation by default.
 
-The library targets operations present on standard Sub2API deployments: account balance, platform quotas, usage history and statistics, API keys, groups, subscriptions, announcements, and redemption.
+The library targets operations present on standard Sub2API deployments: account balance, optional payment deposits, payment orders, platform quotas, usage history and statistics, API keys, groups, subscriptions, announcements, and redemption.
 
 ## Install
 
@@ -157,6 +157,39 @@ result = client.redeem("REDEMPTION-CODE")
 redemption_history = client.redeem.history()
 ```
 
+## Deposits and payment
+
+Payment is optional and must be enabled and configured by the instance administrator. Inspect the checkout configuration before offering a deposit:
+
+```python
+checkout = client.payment.checkout_info()
+
+if checkout.methods:
+    order = client.deposit(
+        10,
+        payment_type="stripe",
+        return_url="https://app.example.com/payment/result",
+    )
+    print(order.order_id, order.pay_url, order.qr_code, order.client_secret)
+```
+
+Available payment methods depend on the instance and can include `alipay`, `wxpay`, `stripe`, and `airwallex`. The returned order contains the provider-specific checkout data: a hosted payment URL, QR code, Stripe client secret, or WeChat OAuth/JSAPI payload. Creating the order does not credit the balance; the configured provider must confirm payment before the instance completes the deposit.
+
+Use the payment resource to inspect and manage the order:
+
+```python
+pending = client.payment.get(order.order_id)
+verified = client.payment.verify(order.out_trade_no)
+orders = client.payment.list(status="COMPLETED", order_type="balance")
+client.payment.cancel(order.order_id)
+```
+
+An instance without payment configuration returns its normal typed API error, including `PAYMENT_DISABLED` or `NO_AVAILABLE_INSTANCE`, rather than silently treating a deposit as successful. Public order recovery is also available when a checkout flow has a signed resume token:
+
+```python
+public_order = client.payment.resolve_public(order.resume_token)
+```
+
 ## Fork-specific endpoints
 
 `request()` provides the same authentication, envelope handling, timezone parameter, refresh behavior, and error mapping for relative endpoints that are not part of the stable resource API.

{sub2api-0.1.1 → sub2api-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sub2api"
-version = "0.1.1"
+version = "0.2.0"
 description = "Python client for the user-facing API of Sub2API instances"
 readme = "README.md"
 requires-python = ">=3.10"

{sub2api-0.1.1 → sub2api-0.2.0}/src/sub2api/__init__.py

@@ -17,14 +17,21 @@ from ._models import (
     Announcement,
     APIKey,
     Balance,
+    CheckoutInfo,
     Group,
     KeyGroupMultiplier,
     Page,
+    PaymentConfig,
+    PaymentMethodLimit,
+    PaymentOrder,
+    PaymentOrderCreation,
     PlatformQuota,
+    PublicPaymentOrder,
     Redemption,
     Resource,
     SessionTokens,
     Subscription,
+    SubscriptionPlan,
     UsageRecord,
     User,
 )
@@ -35,15 +42,21 @@ __all__ = [
     "Announcement",
     "AuthenticationError",
     "Balance",
+    "CheckoutInfo",
     "ConfigurationError",
     "ConflictError",
     "Group",
     "KeyGroupMultiplier",
     "NotFoundError",
     "Page",
+    "PaymentConfig",
+    "PaymentMethodLimit",
+    "PaymentOrder",
+    "PaymentOrderCreation",
     "PermissionDeniedError",
     "PlatformQuota",
     "ProtocolError",
+    "PublicPaymentOrder",
     "RateLimitError",
     "Redemption",
     "Resource",
@@ -51,6 +64,7 @@ __all__ = [
     "Sub2API",
     "Sub2APIError",
     "Subscription",
+    "SubscriptionPlan",
     "TransportError",
     "TwoFactorRequired",
     "UsageRecord",
@@ -58,4 +72,4 @@ __all__ = [
     "ValidationError",
 ]
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"

{sub2api-0.1.1 → sub2api-0.2.0}/src/sub2api/_client.py

@@ -22,12 +22,13 @@ from ._exceptions import (
     TwoFactorRequired,
     ValidationError,
 )
-from ._models import Balance, Resource, SessionTokens, User
+from ._models import Balance, PaymentOrderCreation, Resource, SessionTokens, User
 from ._resources import (
     AccountResource,
     AnnouncementsResource,
     GroupsResource,
     KeysResource,
+    PaymentResource,
     RedeemResource,
     SubscriptionsResource,
     UsageResource,
@@ -146,10 +147,7 @@ class Sub2API:
         self._owns_http_client = session is None
         if session is None:
             if impersonate:
-                self._http: Any = cast(
-                    Any,
-                    curl_requests.Session(impersonate=impersonate),
-                )
+                self._http: Any = cast(Any, curl_requests.Session)(impersonate=impersonate)
             else:
                 self._http = cast(Any, curl_requests.Session())
         else:
@@ -161,6 +159,7 @@ class Sub2API:
         self.history = self.usage
         self.subscriptions = SubscriptionsResource(self)
         self.announcements = AnnouncementsResource(self)
+        self.payment = PaymentResource(self)
         self.redeem = RedeemResource(self)
 
     @property
@@ -281,6 +280,27 @@ class Sub2API:
     def balance(self) -> Balance:
         return self.account.balance()
 
+    def deposit(
+        self,
+        amount: int | float,
+        payment_type: str,
+        *,
+        return_url: str | None = None,
+        payment_source: str | None = None,
+        openid: str | None = None,
+        wechat_resume_token: str | None = None,
+        is_mobile: bool | None = None,
+    ) -> PaymentOrderCreation:
+        return self.payment.deposit(
+            amount,
+            payment_type,
+            return_url=return_url,
+            payment_source=payment_source,
+            openid=openid,
+            wechat_resume_token=wechat_resume_token,
+            is_mobile=is_mobile,
+        )
+
     def public_settings(self) -> Resource:
         data = self._request(
             "GET",
@@ -376,7 +396,7 @@ class Sub2API:
         request_headers = {
             "Accept": "application/json",
             "Accept-Language": self.language,
-            "User-Agent": "sub2api-python/0.1.0",
+            "User-Agent": "sub2api-python/0.2.0",
             "X-User-UI-Request": "1",
         }
         if authenticated and self._tokens.access_token:

{sub2api-0.1.1 → sub2api-0.2.0}/src/sub2api/_models.py

@@ -11,10 +11,12 @@ _SENSITIVE_FIELDS = frozenset(
     {
         "access_token",
         "authorization",
+        "client_secret",
         "code",
         "cookie",
         "custom_key",
         "key",
+        "openid",
         "password",
         "refresh_token",
         "temp_token",
@@ -103,6 +105,34 @@ class Redemption(Resource):
     """A redemption result or history item."""
 
 
+class PaymentConfig(Resource):
+    """Payment availability and account recharge configuration."""
+
+
+class PaymentMethodLimit(Resource):
+    """Limits and fee information for one payment method."""
+
+
+class CheckoutInfo(Resource):
+    """Payment methods and configuration used to start checkout."""
+
+
+class SubscriptionPlan(Resource):
+    """A subscription plan available for purchase."""
+
+
+class PaymentOrder(Resource):
+    """A user payment or balance-recharge order."""
+
+
+class PaymentOrderCreation(Resource):
+    """Checkout details returned after creating a payment order."""
+
+
+class PublicPaymentOrder(Resource):
+    """Non-sensitive payment order data returned by public recovery endpoints."""
+
+
 @dataclass(frozen=True)
 class KeyGroupMultiplier:
     """The group multiplier resolved for one API key."""

{sub2api-0.1.1 → sub2api-0.2.0}/src/sub2api/_resources.py

@@ -11,13 +11,19 @@ from ._models import (
     Announcement,
     APIKey,
     Balance,
+    CheckoutInfo,
     Group,
     KeyGroupMultiplier,
     Page,
+    PaymentConfig,
+    PaymentOrder,
+    PaymentOrderCreation,
     PlatformQuota,
+    PublicPaymentOrder,
     Redemption,
     Resource,
     Subscription,
+    SubscriptionPlan,
     UsageRecord,
     User,
 )
@@ -62,6 +68,14 @@ def _nonnegative(value: int | float, name: str) -> int | float:
     return value
 
 
+def _amount(value: int | float, name: str = "amount") -> int | float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(f"{name} must be a positive finite number")
+    if not math.isfinite(value) or value <= 0:
+        raise ValueError(f"{name} must be a positive finite number")
+    return value
+
+
 def _date(value: date | str | None) -> str | None:
     if value is None:
         return None
@@ -105,6 +119,209 @@ class AccountResource:
         return tuple(PlatformQuota(item) for item in quotas if isinstance(item, Mapping))
 
 
+class PaymentResource:
+    def __init__(self, client: Sub2API) -> None:
+        self._client = client
+
+    def config(self) -> PaymentConfig:
+        data = self._client.request("GET", "payment/config")
+        return PaymentConfig(_mapping(data, "payment config"))
+
+    def checkout_info(self) -> CheckoutInfo:
+        data = self._client.request("GET", "payment/checkout-info")
+        return CheckoutInfo(_mapping(data, "checkout info"))
+
+    def limits(self) -> Resource:
+        return Resource(_mapping(self._client.request("GET", "payment/limits"), "payment limits"))
+
+    def plans(self) -> tuple[SubscriptionPlan, ...]:
+        data = _list(self._client.request("GET", "payment/plans"), "subscription plans")
+        return tuple(SubscriptionPlan(item) for item in data if isinstance(item, Mapping))
+
+    def create_order(
+        self,
+        amount: int | float,
+        payment_type: str,
+        *,
+        order_type: Literal["balance", "subscription"] = "balance",
+        plan_id: int | None = None,
+        return_url: str | None = None,
+        payment_source: str | None = None,
+        openid: str | None = None,
+        wechat_resume_token: str | None = None,
+        is_mobile: bool | None = None,
+    ) -> PaymentOrderCreation:
+        amount = _amount(amount)
+        if not payment_type.strip():
+            raise ValueError("payment_type must not be empty")
+        if order_type not in {"balance", "subscription"}:
+            raise ValueError("order_type must be 'balance' or 'subscription'")
+        if order_type == "subscription" and plan_id is None:
+            raise ValueError("plan_id is required for subscription orders")
+        if plan_id is not None:
+            _positive(plan_id, "plan_id")
+        if is_mobile is not None and not isinstance(is_mobile, bool):
+            raise ValueError("is_mobile must be a boolean")
+        payload: dict[str, Any] = {
+            "amount": amount,
+            "payment_type": payment_type,
+            "order_type": order_type,
+        }
+        optional = {
+            "plan_id": plan_id,
+            "return_url": return_url,
+            "payment_source": payment_source,
+            "openid": openid,
+            "wechat_resume_token": wechat_resume_token,
+            "is_mobile": is_mobile,
+        }
+        payload.update({key: value for key, value in optional.items() if value is not None})
+        data = self._client.request("POST", "payment/orders", json=payload)
+        return PaymentOrderCreation(_mapping(data, "created payment order"))
+
+    def deposit(
+        self,
+        amount: int | float,
+        payment_type: str,
+        *,
+        return_url: str | None = None,
+        payment_source: str | None = None,
+        openid: str | None = None,
+        wechat_resume_token: str | None = None,
+        is_mobile: bool | None = None,
+    ) -> PaymentOrderCreation:
+        return self.create_order(
+            amount,
+            payment_type,
+            order_type="balance",
+            return_url=return_url,
+            payment_source=payment_source,
+            openid=openid,
+            wechat_resume_token=wechat_resume_token,
+            is_mobile=is_mobile,
+        )
+
+    def create_deposit(
+        self,
+        amount: int | float,
+        payment_type: str,
+        *,
+        return_url: str | None = None,
+        payment_source: str | None = None,
+        openid: str | None = None,
+        wechat_resume_token: str | None = None,
+        is_mobile: bool | None = None,
+    ) -> PaymentOrderCreation:
+        return self.deposit(
+            amount,
+            payment_type,
+            return_url=return_url,
+            payment_source=payment_source,
+            openid=openid,
+            wechat_resume_token=wechat_resume_token,
+            is_mobile=is_mobile,
+        )
+
+    def list(
+        self,
+        *,
+        page: int = 1,
+        page_size: int = 20,
+        status: str | None = None,
+        order_type: str | None = None,
+        payment_type: str | None = None,
+    ) -> Page[PaymentOrder]:
+        params = {
+            "page": _positive(page, "page"),
+            "page_size": _positive(page_size, "page_size"),
+            "status": status,
+            "order_type": order_type,
+            "payment_type": payment_type,
+        }
+        return _page(
+            self._client.request("GET", "payment/orders/my", params=params),
+            PaymentOrder,
+            "payment orders",
+        )
+
+    def list_orders(self, **kwargs: Any) -> Page[PaymentOrder]:
+        return self.list(**kwargs)
+
+    def get(self, order_id: int) -> PaymentOrder:
+        order_id = _positive(order_id, "order_id")
+        data = self._client.request("GET", f"payment/orders/{order_id}")
+        return PaymentOrder(_mapping(data, "payment order"))
+
+    def get_order(self, order_id: int) -> PaymentOrder:
+        return self.get(order_id)
+
+    def cancel(self, order_id: int) -> Resource | None:
+        order_id = _positive(order_id, "order_id")
+        data = self._client.request("POST", f"payment/orders/{order_id}/cancel")
+        return Resource(data) if isinstance(data, Mapping) else None
+
+    def cancel_order(self, order_id: int) -> Resource | None:
+        return self.cancel(order_id)
+
+    def verify(self, out_trade_no: str) -> PaymentOrder:
+        if not out_trade_no.strip():
+            raise ValueError("out_trade_no must not be empty")
+        data = self._client.request(
+            "POST",
+            "payment/orders/verify",
+            json={"out_trade_no": out_trade_no},
+        )
+        return PaymentOrder(_mapping(data, "verified payment order"))
+
+    def verify_order(self, out_trade_no: str) -> PaymentOrder:
+        return self.verify(out_trade_no)
+
+    def verify_public(self, out_trade_no: str) -> PublicPaymentOrder:
+        if not out_trade_no.strip():
+            raise ValueError("out_trade_no must not be empty")
+        data = self._client.request(
+            "POST",
+            "payment/public/orders/verify",
+            json={"out_trade_no": out_trade_no},
+            authenticated=False,
+        )
+        return PublicPaymentOrder(_mapping(data, "public payment order"))
+
+    def resolve_public(self, resume_token: str) -> PublicPaymentOrder:
+        if not resume_token.strip():
+            raise ValueError("resume_token must not be empty")
+        data = self._client.request(
+            "POST",
+            "payment/public/orders/resolve",
+            json={"resume_token": resume_token},
+            authenticated=False,
+        )
+        return PublicPaymentOrder(_mapping(data, "public payment order"))
+
+    def request_refund(self, order_id: int, reason: str) -> Resource | None:
+        order_id = _positive(order_id, "order_id")
+        if not reason.strip():
+            raise ValueError("reason must not be empty")
+        data = self._client.request(
+            "POST",
+            f"payment/orders/{order_id}/refund-request",
+            json={"reason": reason},
+        )
+        return Resource(data) if isinstance(data, Mapping) else None
+
+    def refund_eligible_providers(self) -> tuple[str, ...]:
+        data = _mapping(
+            self._client.request("GET", "payment/orders/refund-eligible-providers"),
+            "refund eligibility",
+        )
+        provider_ids = data.get("provider_instance_ids", [])
+        if not isinstance(provider_ids, list) or any(
+            not isinstance(item, str) for item in provider_ids
+        ):
+            raise ProtocolError("refund eligibility contained invalid provider IDs")
+        return tuple(provider_ids)
+
+
 class KeysResource:
     def __init__(self, client: Sub2API) -> None:
         self._client = client

{sub2api-0.1.1 → sub2api-0.2.0}/tests/test_resources.py

@@ -224,3 +224,130 @@ def test_history_filters_and_boolean_query_encoding() -> None:
     page = client.history(start_date="2025-01-01", end_date="2025-01-31", stream=True)
 
     assert page.items[0].model == "claude"
+
+
+def test_payment_config_deposit_and_order_lifecycle() -> None:
+    seen: list[tuple[str, str, Any]] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = json.loads(request.content) if request.content else None
+        seen.append((request.method, request.url.path, body))
+        if request.url.path.endswith("/payment/config"):
+            return success({"enabled": True, "min_amount": 1, "enabled_payment_types": ["stripe"]})
+        if request.url.path.endswith("/payment/checkout-info"):
+            return success({"methods": {"stripe": {"available": True}}, "global_min": 1})
+        if request.url.path.endswith("/payment/limits"):
+            return success({"methods": {"stripe": {"single_min": 1}}})
+        if request.url.path.endswith("/payment/orders") and request.method == "POST":
+            assert request.headers["Authorization"] == "Bearer token"
+            assert body == {
+                "amount": 10,
+                "payment_type": "stripe",
+                "order_type": "balance",
+                "return_url": "https://app.example.test/payment/result",
+                "payment_source": "hosted_redirect",
+                "is_mobile": False,
+            }
+            return success(
+                {
+                    "order_id": 42,
+                    "amount": 10,
+                    "pay_amount": 10.25,
+                    "fee_rate": 2.5,
+                    "payment_type": "stripe",
+                    "client_secret": "secret-value",
+                    "out_trade_no": "SUB2API-42",
+                    "expires_at": "2026-01-01T00:30:00Z",
+                }
+            )
+        if request.url.path.endswith("/payment/orders/42"):
+            return success(
+                {
+                    "id": 42,
+                    "amount": 10,
+                    "status": "PENDING",
+                    "order_type": "balance",
+                }
+            )
+        if request.url.path.endswith("/payment/orders/my"):
+            assert request.url.params["status"] == "COMPLETED"
+            assert request.url.params["order_type"] == "balance"
+            return success(
+                {
+                    "items": [{"id": 42, "status": "COMPLETED"}],
+                    "total": 1,
+                    "page": 1,
+                    "page_size": 20,
+                    "pages": 1,
+                }
+            )
+        if request.url.path.endswith("/payment/orders/verify"):
+            assert body == {"out_trade_no": "SUB2API-42"}
+            return success({"id": 42, "status": "COMPLETED", "out_trade_no": "SUB2API-42"})
+        if request.url.path.endswith("/payment/orders/42/cancel"):
+            return success({"message": "order cancelled"})
+        if request.url.path.endswith("/payment/orders/refund-eligible-providers"):
+            return success({"provider_instance_ids": ["stripe-1"]})
+        raise AssertionError(f"unexpected request: {request.method} {request.url}")
+
+    client = Sub2API(
+        "https://example.test",
+        access_token="token",
+        session=TestSession(handler),
+    )
+
+    assert client.payment.config().enabled
+    assert client.payment.checkout_info().methods.stripe.available
+    assert client.payment.limits().methods.stripe.single_min == 1
+    created = client.deposit(
+        10,
+        "stripe",
+        return_url="https://app.example.test/payment/result",
+        payment_source="hosted_redirect",
+        is_mobile=False,
+    )
+    assert created.order_id == 42
+    assert created.client_secret == "secret-value"
+    assert client.payment.get_order(42).status == "PENDING"
+    assert (
+        client.payment.list_orders(status="COMPLETED", order_type="balance").items[0].status
+        == "COMPLETED"
+    )
+    assert client.payment.verify_order("SUB2API-42").status == "COMPLETED"
+    assert client.payment.cancel_order(42).message == "order cancelled"
+    assert client.payment.refund_eligible_providers() == ("stripe-1",)
+
+    assert seen[0][1].endswith("/payment/config")
+
+
+def test_payment_public_order_recovery_does_not_send_authentication() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.path.endswith("/payment/public/orders/verify")
+        assert "Authorization" not in request.headers
+        assert json.loads(request.content) == {"out_trade_no": "SUB2API-42"}
+        return success({"out_trade_no": "SUB2API-42", "status": "COMPLETED", "paid": True})
+
+    client = Sub2API(
+        "https://example.test",
+        access_token="token",
+        session=TestSession(handler),
+    )
+
+    result = client.payment.verify_public("SUB2API-42")
+
+    assert result.paid
+    assert result.status == "COMPLETED"
+
+
+def test_payment_order_validation_happens_before_network_request() -> None:
+    client = Sub2API(
+        "https://example.test",
+        session=TestSession(lambda request: success({})),
+    )
+
+    with pytest.raises(ValueError, match="positive finite"):
+        client.payment.deposit(0, "stripe")
+    with pytest.raises(ValueError, match="payment_type"):
+        client.payment.deposit(10, " ")
+    with pytest.raises(ValueError, match="plan_id"):
+        client.payment.create_order(10, "stripe", order_type="subscription")