pyXRocketAPI 0.1.0__tar.gz → 0.2.0__tar.gz

{pyxrocketapi-0.1.0 → pyxrocketapi-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyXRocketAPI
-Version: 0.1.0
+Version: 0.2.0
 Summary: Python client for the xRocket Pay API
 Author: Badiboy
 License-Expression: MIT
@@ -17,7 +17,11 @@ License-File: LICENSE
 Requires-Dist: requests>=2.28
 Dynamic: license-file
 
-# pyXRocketAPI
+[![PyPi Package Version](https://img.shields.io/pypi/v/pyXRocketAPI.svg)](https://pypi.python.org/pypi/pyXRocketAPI)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/pyXRocketAPI.svg)](https://pypi.python.org/pypi/pyXRocketAPI)
+[![PyPi downloads](https://img.shields.io/pypi/dm/pyXRocketAPI.svg)](https://pypi.org/project/pyXRocketAPI/)
+
+# <p align="center">pyXRocketAPI</p>
 
 **pyXRocketAPI** is a Python client for the [xRocket Pay API](https://docs.xrocket.exchange/api/pay/pay-api-overview). It supports application information, balances, invoices, cheques, payouts, withdrawals, currency rates, and health checks.
 

{pyxrocketapi-0.1.0 → pyxrocketapi-0.2.0}/README.md

@@ -1,4 +1,8 @@
-# pyXRocketAPI
+[![PyPi Package Version](https://img.shields.io/pypi/v/pyXRocketAPI.svg)](https://pypi.python.org/pypi/pyXRocketAPI)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/pyXRocketAPI.svg)](https://pypi.python.org/pypi/pyXRocketAPI)
+[![PyPi downloads](https://img.shields.io/pypi/dm/pyXRocketAPI.svg)](https://pypi.org/project/pyXRocketAPI/)
+
+# <p align="center">pyXRocketAPI</p>
 
 **pyXRocketAPI** is a Python client for the [xRocket Pay API](https://docs.xrocket.exchange/api/pay/pay-api-overview). It supports application information, balances, invoices, cheques, payouts, withdrawals, currency rates, and health checks.
 

{pyxrocketapi-0.1.0 → pyxrocketapi-0.2.0}/pyXRocketAPI/__init__.py

@@ -1,3 +1,5 @@
 """Public API for pyXRocketAPI."""
 
 from .api import *
+from .exceptions import *
+from .webhooks import *

{pyxrocketapi-0.1.0 → pyxrocketapi-0.2.0}/pyXRocketAPI/exceptions.py

@@ -20,3 +20,19 @@ class xRocketAPIException(Exception):
         self.instance = instance
         self.kind = kind
         self.info = info
+
+
+class xRocketWebhookException(ValueError):
+    """Base class for errors while validating or parsing an xRocket webhook."""
+
+
+class xRocketWebhookParseException(xRocketWebhookException):
+    """Webhook body is not valid JSON or does not have the expected structure."""
+
+
+class xRocketWebhookSignatureException(xRocketWebhookException):
+    """Webhook signature is absent or does not match the supplied secret."""
+
+
+class xRocketWebhookUnsupportedVersionException(xRocketWebhookSignatureException):
+    """Webhook uses a signature scheme version unsupported by this library."""

{pyxrocketapi-0.1.0 → pyxrocketapi-0.2.0}/pyXRocketAPI/models.py

@@ -68,8 +68,8 @@ class App(xRocketObject):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/app-controller-get-app
 
-    :ivar id: No description is provided.
-    :ivar name: Name of current app.
+    :param id: No description is provided.
+    :param name: Name of current app.
     """
     def __init__(self):
         self.id = None
@@ -87,10 +87,10 @@ class Balance(xRocketObject):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/app-controller-get-app-balances
 
-    :ivar asset: Balance asset.
-    :ivar balance: Asset balance.
-    :ivar available: Available balance.
-    :ivar holds: Holds balance.
+    :param asset: Balance asset.
+    :param balance: Asset balance.
+    :param available: Available balance.
+    :param holds: Holds balance.
     """
     def __init__(self):
         self.asset = None
@@ -110,9 +110,9 @@ class InvoiceLinks(xRocketObject):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-controller-get-invoice
 
-    :ivar telegramBotLink: Invoice telegram bot link.
-    :ivar telegramMiniAppLink: Invoice telegram mini app link.
-    :ivar webLink: Invoice web link.
+    :param telegramBotLink: Invoice telegram bot link.
+    :param telegramMiniAppLink: Invoice telegram mini app link.
+    :param webLink: Invoice web link.
     """
     def __init__(self):
         self.telegramBotLink = None
@@ -131,21 +131,21 @@ class Invoice(xRocketObject):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-controller-get-invoice
 
-    :ivar id: Invoice id.
-    :ivar priceAmount: Invoice price amount.
-    :ivar minPayment: Minimum payment amount (for open-amount invoices).
-    :ivar priceCurrency: Invoice price currency (crypto or fiat).
-    :ivar payCurrencies: Currencies which can be used to pay the invoice (crypto or fiat).
-    :ivar clientInvoiceId: Your unique identifier for this invoice to link with your internal system (e.g., order ID).
-    :ivar description: Description for invoice.
-    :ivar expiresIn: Invoice expires in milliseconds (from creation time).
-    :ivar createdAt: Invoice creation time.
-    :ivar expiresAt: Invoice expiration time (null if no expiration).
-    :ivar status: Invoice status. **WARNING**: This list may be extended in the future. Always use exact status comparison and handle unknown statuses gracefully.
-    :ivar callback: No description is provided.
-    :ivar url: No description is provided.
-    :ivar customer: No description is provided.
-    :ivar links: No description is provided.
+    :param id: Invoice id.
+    :param priceAmount: Invoice price amount.
+    :param minPayment: Minimum payment amount (for open-amount invoices).
+    :param priceCurrency: Invoice price currency (crypto or fiat).
+    :param payCurrencies: Currencies which can be used to pay the invoice (crypto or fiat).
+    :param clientInvoiceId: Your unique identifier for this invoice to link with your internal system (e.g., order ID).
+    :param description: Description for invoice.
+    :param expiresIn: Invoice expires in milliseconds (from creation time).
+    :param createdAt: Invoice creation time.
+    :param expiresAt: Invoice expiration time (null if no expiration).
+    :param status: Invoice status. **WARNING**: This list may be extended in the future. Always use exact status comparison and handle unknown statuses gracefully.
+    :param callback: No description is provided.
+    :param url: No description is provided.
+    :param customer: No description is provided.
+    :param links: No description is provided.
     """
     def __init__(self):
         self.id = None
@@ -179,9 +179,9 @@ class ChequeLinks(xRocketObject):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/cheque-controller-get-cheque
 
-    :ivar telegramBotLink: Cheque activation telegram bot link.
-    :ivar telegramMiniAppLink: Cheque activation telegram mini app link (soon).
-    :ivar webLink: Cheque activation web link (soon).
+    :param telegramBotLink: Cheque activation telegram bot link.
+    :param telegramMiniAppLink: Cheque activation telegram mini app link (soon).
+    :param webLink: Cheque activation web link (soon).
     """
     def __init__(self):
         self.telegramBotLink = None
@@ -200,17 +200,17 @@ class Cheque(xRocketObject):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/cheque-controller-get-cheque
 
-    :ivar chequeId: Cheque ID.
-    :ivar clientChequeId: Unique cheque ID in your system to prevent double spends.
-    :ivar asset: Currency of transfer.
-    :ivar description: Description for cheque.
-    :ivar targetType: Target type for cheque.
-    :ivar target: Target for cheque.
-    :ivar links: Cheque activation links.
-    :ivar state: Cheque state.
-    :ivar deleted: Cheque is cancelled and the reserved funds are returned to the application balance.
-    :ivar callback: No description is provided.
-    :ivar url: No description is provided.
+    :param chequeId: Cheque ID.
+    :param clientChequeId: Unique cheque ID in your system to prevent double spends.
+    :param asset: Currency of transfer.
+    :param description: Description for cheque.
+    :param targetType: Target type for cheque.
+    :param target: Target for cheque.
+    :param links: Cheque activation links.
+    :param state: Cheque state.
+    :param deleted: Cheque is cancelled and the reserved funds are returned to the application balance.
+    :param callback: No description is provided.
+    :param url: No description is provided.
     """
     def __init__(self):
         self.chequeId = None
@@ -240,15 +240,15 @@ class Payout(xRocketObject):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/payout-controller-get-payout
 
-    :ivar payoutId: Payout ID.
-    :ivar clientPayoutId: Unique payout ID in your system to prevent double spends.
-    :ivar target: Target.
-    :ivar targetType: Target type.
-    :ivar asset: Asset of payout.
-    :ivar amount: Payout amount.
-    :ivar description: Payout description.
-    :ivar status: Payout status.
-    :ivar callback: Webhook settings of this payout.
+    :param payoutId: Payout ID.
+    :param clientPayoutId: Unique payout ID in your system to prevent double spends.
+    :param target: Target.
+    :param targetType: Target type.
+    :param asset: Asset of payout.
+    :param amount: Payout amount.
+    :param description: Payout description.
+    :param status: Payout status.
+    :param callback: Webhook settings of this payout.
     """
     def __init__(self):
         self.payoutId = None
@@ -273,16 +273,16 @@ class Withdrawal(xRocketObject):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/withdrawal-controller-get-withdrawal
 
-    :ivar withdrawalId: Unique withdrawal ID in your system to prevent double spends.
-    :ivar network: Network code.
-    :ivar address: Withdrawal address.
-    :ivar asset: Asset code.
-    :ivar amount: Withdrawal amount. 9 decimal places, others cut off.
-    :ivar status: Withdrawal status.
-    :ivar comment: Withdrawal comment.
-    :ivar txHash: Withdrawal TX hash. Provided only after withdrawal.
-    :ivar txLink: Withdrawal TX link. Provided only after withdrawal.
-    :ivar callback: Webhook settings of this withdrawal.
+    :param withdrawalId: Unique withdrawal ID in your system to prevent double spends.
+    :param network: Network code.
+    :param address: Withdrawal address.
+    :param asset: Asset code.
+    :param amount: Withdrawal amount. 9 decimal places, others cut off.
+    :param status: Withdrawal status.
+    :param comment: Withdrawal comment.
+    :param txHash: Withdrawal TX hash. Provided only after withdrawal.
+    :param txLink: Withdrawal TX link. Provided only after withdrawal.
+    :param callback: Webhook settings of this withdrawal.
     """
     def __init__(self):
         self.withdrawalId = None
@@ -308,7 +308,7 @@ class CurrencyNetwork(xRocketObject):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/currencies-controller-get-currencies
 
-    :ivar code: Network code.
+    :param code: Network code.
     """
     def __init__(self):
         self.code = None
@@ -325,10 +325,10 @@ class Currency(xRocketObject):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/currencies-controller-get-currencies
 
-    :ivar code: No description is provided.
-    :ivar title: No description is provided.
-    :ivar kind: No description is provided.
-    :ivar networks: No description is provided.
+    :param code: No description is provided.
+    :param title: No description is provided.
+    :param kind: No description is provided.
+    :param networks: No description is provided.
     """
     def __init__(self):
         self.code = None
@@ -350,8 +350,8 @@ class Rate(xRocketObject):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/rate-controller-get-rates
 
-    :ivar currency: No description is provided.
-    :ivar rate: Current rate.
+    :param currency: No description is provided.
+    :param rate: Current rate.
     """
     def __init__(self):
         self.currency = None
@@ -369,8 +369,8 @@ class xPage(xRocketObject):
 
     This is an SDK base model; the API has no standalone page endpoint.
 
-    :ivar items: No description is provided.
-    :ivar pagination: No description is provided.
+    :param items: No description is provided.
+    :param pagination: No description is provided.
     """
     def __init__(self):
         self.items = []
@@ -388,8 +388,8 @@ class CursorPagination(xRocketObject):
 
     This shared response fragment has no standalone API endpoint.
 
-    :ivar total: Total quantity of campaigns.
-    :ivar next: Cursor for the next page of results.
+    :param total: Total quantity of campaigns.
+    :param next: Cursor for the next page of results.
     """
     def __init__(self):
         self.total = None
@@ -407,7 +407,7 @@ class InvoicePaymentsPagination(xRocketObject):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-controller-get-invoice-payments
 
-    :ivar next: Cursor for the next page of results.
+    :param next: Cursor for the next page of results.
     """
     def __init__(self):
         self.next = None
@@ -424,14 +424,14 @@ class InvoicePayment(xRocketObject):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-controller-get-invoice-payments
 
-    :ivar id: Unique payment id. Use it to match webhook events with the invoice payments endpoint.
-    :ivar status: Invoice status. **WARNING**: This list may be extended in the future. Always use exact status comparison and handle unknown statuses gracefully.
-    :ivar finalizedAt: When payment reached final state (null for in-progress payments).
-    :ivar payAmount: Gross amount payer sent in total across all transactions of this payment (before fees).
-    :ivar payCurrency: Currency payer used.
-    :ivar receiveAmount: Net amount merchant receives after fees, summed across all transactions of this payment (in invoice priceCurrency).
-    :ivar receiveCurrency: Currency merchant receives (= invoice priceCurrency).
-    :ivar transactions: No description is provided.
+    :param id: Unique payment id. Use it to match webhook events with the invoice payments endpoint.
+    :param status: Invoice status. **WARNING**: This list may be extended in the future. Always use exact status comparison and handle unknown statuses gracefully.
+    :param finalizedAt: When payment reached final state (null for in-progress payments).
+    :param payAmount: Gross amount payer sent in total across all transactions of this payment (before fees).
+    :param payCurrency: Currency payer used.
+    :param receiveAmount: Net amount merchant receives after fees, summed across all transactions of this payment (in invoice priceCurrency).
+    :param receiveCurrency: Currency merchant receives (= invoice priceCurrency).
+    :param transactions: No description is provided.
     """
     def __init__(self):
         self.id = None
@@ -455,8 +455,8 @@ class InvoicesList(xPage):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-controller-get-invoices
 
-    :ivar items: No description is provided.
-    :ivar pagination: No description is provided.
+    :param items: No description is provided.
+    :param pagination: No description is provided.
     """
     @classmethod
     def de_json(cls, json_dict):
@@ -474,8 +474,8 @@ class InvoicePaymentsList(xPage):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-controller-get-invoice-payments
 
-    :ivar items: No description is provided.
-    :ivar pagination: No description is provided.
+    :param items: No description is provided.
+    :param pagination: No description is provided.
     """
     @classmethod
     def de_json(cls, json_dict):
@@ -493,8 +493,8 @@ class ChequesList(xPage):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/cheque-controller-get-cheques
 
-    :ivar items: No description is provided.
-    :ivar pagination: No description is provided.
+    :param items: No description is provided.
+    :param pagination: No description is provided.
     """
     @classmethod
     def de_json(cls, json_dict):
@@ -512,8 +512,8 @@ class PayoutsList(xPage):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/payout-controller-get-list-payouts
 
-    :ivar items: No description is provided.
-    :ivar pagination: No description is provided.
+    :param items: No description is provided.
+    :param pagination: No description is provided.
     """
     @classmethod
     def de_json(cls, json_dict):
@@ -531,8 +531,8 @@ class WithdrawalsList(xPage):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/withdrawal-controller-get-withdrawals
 
-    :ivar items: No description is provided.
-    :ivar pagination: No description is provided.
+    :param items: No description is provided.
+    :param pagination: No description is provided.
     """
     @classmethod
     def de_json(cls, json_dict):
@@ -550,11 +550,11 @@ class InvoicePaymentAddress(xRocketObject):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-payment-controller-create-invoice-payment-address
 
-    :ivar address: Deposit address.
-    :ivar payCurrency: Currency code.
-    :ivar payNetwork: Network code.
-    :ivar expiresAt: Payment expired at.
-    :ivar minAmount: Minimum deposit amount (invoice has no fixed amount).
+    :param address: Deposit address.
+    :param payCurrency: Currency code.
+    :param payNetwork: Network code.
+    :param expiresAt: Payment expired at.
+    :param minAmount: Minimum deposit amount (invoice has no fixed amount).
     """
     def __init__(self):
         self.address = None
@@ -575,10 +575,10 @@ class WithdrawalQuotas(xRocketObject):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/withdrawal-controller-get-withdrawal-fees
 
-    :ivar withdrawMinSize: Minimum withdrawal amount.
-    :ivar withdrawFee: Withdrawal fee.
-    :ivar withdrawFeeAsset: Withdrawal fee asset.
-    :ivar precision: Floating point precision.
+    :param withdrawMinSize: Minimum withdrawal amount.
+    :param withdrawFee: Withdrawal fee.
+    :param withdrawFeeAsset: Withdrawal fee asset.
+    :param precision: Floating point precision.
     """
     def __init__(self):
         self.withdrawMinSize = None
@@ -598,9 +598,9 @@ class WithdrawalLink(xRocketObject):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/withdrawal-links-controller-create-withdrawal-link
 
-    :ivar telegramBotLink: Withdrawal telegram bot link.
-    :ivar telegramMiniAppLink: Withdrawal telegram mini app link (soon).
-    :ivar webLink: Withdrawal web link (soon).
+    :param telegramBotLink: Withdrawal telegram bot link.
+    :param telegramMiniAppLink: Withdrawal telegram mini app link (soon).
+    :param webLink: Withdrawal web link (soon).
     """
     def __init__(self):
         self.telegramBotLink = None
@@ -619,12 +619,12 @@ class MassPayoutReason(xRocketObject):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/mass-payouts-controller-create-mass-payouts
 
-    :ivar type: A URI reference that identifies the problem type.
-    :ivar title: A short, human-readable summary of the problem type.
-    :ivar status: HTTP status code.
-    :ivar detail: A human-readable explanation specific to this occurrence of the problem.
-    :ivar instance: A URI reference that identifies the specific occurrence of the problem.
-    :ivar kind: Problem category for easier error handling.
+    :param type: A URI reference that identifies the problem type.
+    :param title: A short, human-readable summary of the problem type.
+    :param status: HTTP status code.
+    :param detail: A human-readable explanation specific to this occurrence of the problem.
+    :param instance: A URI reference that identifies the specific occurrence of the problem.
+    :param kind: Problem category for easier error handling.
     """
     def __init__(self):
         self.type = None
@@ -646,12 +646,12 @@ class MassPayoutError(xRocketObject):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/mass-payouts-controller-create-mass-payouts
 
-    :ivar target: Target.
-    :ivar targetType: Target type (only TelegramUserId is supported for mass payouts).
-    :ivar amount: Payout amount.
-    :ivar clientPayoutId: Unique payout ID in your system to prevent double spends.
-    :ivar description: Payout description.
-    :ivar reason: Payout error reason.
+    :param target: Target.
+    :param targetType: Target type (only TelegramUserId is supported for mass payouts).
+    :param amount: Payout amount.
+    :param clientPayoutId: Unique payout ID in your system to prevent double spends.
+    :param description: Payout description.
+    :param reason: Payout error reason.
     """
     def __init__(self):
         self.target = None
@@ -676,8 +676,8 @@ class MassPayouts(xRocketObject):
 
     API: https://docs.xrocket.exchange/api/pay/reference/http/mass-payouts-controller-create-mass-payouts
 
-    :ivar successPayouts: Successful payouts.
-    :ivar errorPayouts: Error payouts.
+    :param successPayouts: Successful payouts.
+    :param errorPayouts: Error payouts.
     """
     def __init__(self):
         self.successPayouts = []

{pyxrocketapi-0.1.0 → pyxrocketapi-0.2.0}/pyXRocketAPI/version.py

@@ -1,3 +1,3 @@
 """Package version, read by the build configuration."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

pyxrocketapi-0.2.0/pyXRocketAPI/webhooks.py

@@ -0,0 +1,480 @@
+"""Verification and parsing of xRocket Pay webhooks.
+
+API: https://docs.xrocket.exchange/api/pay/pay-api-overview
+
+This module does not receive HTTP requests and does not depend on Flask,
+FastAPI, Django, or another web framework. Pass the request body and headers
+from the HTTP layer that your application already uses.
+
+Always verify a webhook before parsing or acting on it. The verifier requires
+the original request body, preferably as ``bytes``. Do not pass a JSON object
+that was decoded and serialized again: whitespace, field order, or escaping
+can change and invalidate the signature.
+
+For applications using the current xRocket Pay API, xRocket sends these
+headers:
+
+* ``Signature-Timestamp``: Unix timestamp in milliseconds when the webhook was sent.
+* ``Signature-Version``: Signature scheme version. The current value is ``v1``.
+* ``Signature``: hexadecimal HMAC-SHA-256 signature.
+
+For version ``v1``, the signed byte sequence is::
+    {Signature-Timestamp}.{raw request body}
+
+The application's webhook secret is the HMAC key without transformations.
+Header names are compared case-insensitively. The legacy
+``Rocket-Pay-Signature`` header is intentionally unsupported because it does
+not use the current signature scheme.
+
+Use :func:`parse_and_verify_webhook` for the usual case::
+    event = parse_and_verify_webhook(
+        raw_body=request.body,
+        headers=request.headers,
+        webhook_secret=WEBHOOK_SECRET,
+    )
+
+The returned object is one of :class:`InvoiceStatusChangedWebhook`,
+:class:`PaymentStatusChangedWebhook`, :class:`ChequeWebhook`,
+:class:`PayoutWebhook`, :class:`WithdrawalWebhook`, or
+:class:`UnknownWebhook`.
+
+The top-level webhook ``id`` identifies a delivery and remains stable across
+retries. Persist and deduplicate this value in application storage before an
+irreversible business action. Idempotency storage is deliberately outside this
+library because its implementation depends on the application's database and
+transaction rules.
+
+xRocket can add new event and status values without notice. Unknown webhook
+types or invoice event values become :class:`UnknownWebhook` instead of an
+exception, so an application can log and safely ignore them. Invalid JSON,
+missing required envelope fields, or an invalid signature are errors.
+
+When a payment completes an invoice, xRocket sends both
+``payment_status_changed`` and ``invoice_status_changed``. Delivery order is
+not guaranteed, including after retries. Process each event independently.
+Track successful payments only when ``event`` is
+``payment_status_changed`` and ``event.data.payment.status`` is ``paid``;
+track invoice completion only when ``event`` is
+``invoice_status_changed`` and ``event.data.invoice.status`` is ``paid``.
+Payment finality is indicated by ``event.data.payment.finalizedAt`` not being
+``None``, rather than by relying on one fixed status value.
+
+AI generated. Manually validated.
+"""
+
+import hashlib
+import hmac
+import json
+from collections.abc import Mapping
+from typing import Any
+
+from .exceptions import (
+    xRocketWebhookParseException,
+    xRocketWebhookSignatureException,
+    xRocketWebhookUnsupportedVersionException,
+)
+from .models import Cheque, Invoice, InvoicePayment, Payout, Withdrawal, xRocketObject
+
+
+# noinspection method-overriding
+class xRocketWebhook(xRocketObject):
+    """Base model for an xRocket webhook delivery.
+
+    API: https://docs.xrocket.exchange/api/pay/pay-api-overview
+
+    :param id: Unique webhook delivery id, can be used by the receiver for
+        idempotency.
+    :param timestamp: When webhook was sent.
+    :param type: Webhook type.
+    :param data: Typed webhook payload.
+    """
+
+    def __init__(self):
+        self.id = None
+        self.timestamp = None
+        self.type = None
+        self.data = None
+
+    @classmethod
+    def de_json(cls, json_dict):
+        """Create a webhook model from its parsed envelope dictionary.
+
+        :param json_dict: Parsed webhook envelope.
+        :return: ``xRocketWebhook``.
+        """
+        data = cls.check_json(json_dict)
+        return super(xRocketWebhook, cls).de_json(data, process_mode=2)
+
+
+# noinspection method-overriding
+class InvoiceStatusChangedWebhookData(xRocketObject):
+    """Payload of an ``invoice_status_changed`` webhook.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-controller-create-invoice
+
+    :param event: Event type. This value is ``invoice_status_changed``.
+    :param invoice: Updated invoice.
+    """
+
+    def __init__(self):
+        self.event = None
+        self.invoice = None
+
+    @classmethod
+    def de_json(cls, json_dict):
+        """Create the payload from a parsed webhook dictionary.
+
+        :param json_dict: Parsed invoice-status-changed payload.
+        :return: ``InvoiceStatusChangedWebhookData``.
+        """
+        data = cls.check_json(json_dict)
+        instance = super(InvoiceStatusChangedWebhookData, cls).de_json(data, process_mode=2)
+        instance.invoice = Invoice.de_json(instance.invoice)
+        return instance
+
+
+# noinspection method-overriding
+class PaymentStatusChangedWebhookData(xRocketObject):
+    """Payload of a ``payment_status_changed`` webhook.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-controller-create-invoice
+
+    :param event: Event type. This value is ``payment_status_changed``.
+    :param invoice: Updated invoice.
+    :param payment: Payment received for the invoice or whose status changed.
+    """
+
+    def __init__(self):
+        self.event = None
+        self.invoice = None
+        self.payment = None
+
+    @classmethod
+    def de_json(cls, json_dict):
+        """Create the payload from a parsed webhook dictionary.
+
+        :param json_dict: Parsed payment-status-changed payload.
+        :return: ``PaymentStatusChangedWebhookData``.
+        """
+        data = cls.check_json(json_dict)
+        instance = super(PaymentStatusChangedWebhookData, cls).de_json(data, process_mode=2)
+        instance.invoice = Invoice.de_json(instance.invoice)
+        instance.payment = InvoicePayment.de_json(instance.payment)
+        return instance
+
+
+# noinspection method-overriding
+class InvoiceStatusChangedWebhook(xRocketWebhook):
+    """Invoice webhook reporting an invoice status transition.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-controller-create-invoice
+
+    :param id: Unique webhook delivery id, can be used by the receiver for idempotency.
+    :param timestamp: When webhook was sent.
+    :param type: Webhook type. This value is ``invoice``.
+    :param data: ``InvoiceStatusChangedWebhookData`` payload.
+    """
+
+    @classmethod
+    def de_json(cls, json_dict):
+        """Create the webhook from a parsed envelope dictionary.
+
+        :param json_dict: Parsed invoice webhook envelope.
+        :return: ``InvoiceStatusChangedWebhook``.
+        """
+        data = cls.check_json(json_dict)
+        instance = super(InvoiceStatusChangedWebhook, cls).de_json(data)
+        instance.data = InvoiceStatusChangedWebhookData.de_json(instance.data)
+        return instance
+
+
+# noinspection method-overriding
+class PaymentStatusChangedWebhook(xRocketWebhook):
+    """Invoice webhook reporting a received payment or payment status change.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/invoice-controller-create-invoice
+
+    :param id: Unique webhook delivery id, can be used by the receiver for idempotency.
+    :param timestamp: When webhook was sent.
+    :param type: Webhook type. This value is ``invoice``.
+    :param data: ``PaymentStatusChangedWebhookData`` payload.
+    """
+
+    @classmethod
+    def de_json(cls, json_dict):
+        """Create the webhook from a parsed envelope dictionary.
+
+        :param json_dict: Parsed invoice webhook envelope.
+        :return: ``PaymentStatusChangedWebhook``.
+        """
+        data = cls.check_json(json_dict)
+        instance = super(PaymentStatusChangedWebhook, cls).de_json(data)
+        instance.data = PaymentStatusChangedWebhookData.de_json(instance.data)
+        return instance
+
+
+class ChequeWebhook(xRocketWebhook):
+    """Webhook reporting an update to a cheque.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/cheque-controller-create-cheque
+
+    :param id: Unique webhook delivery id, can be used by the receiver for idempotency.
+    :param timestamp: When webhook was sent.
+    :param type: Webhook type. This value is ``cheque``.
+    :param data: Updated ``Cheque``.
+    """
+
+    @classmethod
+    def de_json(cls, json_dict):
+        """Create the webhook from a parsed envelope dictionary.
+
+        :param json_dict: Parsed cheque webhook envelope.
+        :return: ``ChequeWebhook``.
+        """
+        data = cls.check_json(json_dict)
+        instance = super(ChequeWebhook, cls).de_json(data)
+        instance.data = Cheque.de_json(instance.data)
+        return instance
+
+
+class PayoutWebhook(xRocketWebhook):
+    """Webhook reporting a payout status update.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/payout-controller-payout
+
+    :param id: Unique webhook delivery id, can be used by the receiver for idempotency.
+    :param timestamp: When webhook was sent.
+    :param type: Webhook type. This value is ``payout``.
+    :param data: Updated ``Payout``.
+    """
+
+    @classmethod
+    def de_json(cls, json_dict):
+        """Create the webhook from a parsed envelope dictionary.
+
+        :param json_dict: Parsed payout webhook envelope.
+        :return: ``PayoutWebhook``.
+        """
+        data = cls.check_json(json_dict)
+        instance = super(PayoutWebhook, cls).de_json(data)
+        instance.data = Payout.de_json(instance.data)
+        return instance
+
+
+class WithdrawalWebhook(xRocketWebhook):
+    """Webhook reporting a withdrawal status update.
+
+    API: https://docs.xrocket.exchange/api/pay/reference/http/withdrawal-controller-create-withdrawal
+
+    :param id: Unique webhook delivery id, can be used by the receiver for idempotency.
+    :param timestamp: When webhook was sent.
+    :param type: Webhook type. This value is ``withdrawal``.
+    :param data: Updated ``Withdrawal``.
+    """
+
+    @classmethod
+    def de_json(cls, json_dict):
+        """Create the webhook from a parsed envelope dictionary.
+
+        :param json_dict: Parsed withdrawal webhook envelope.
+        :return: ``WithdrawalWebhook``.
+        """
+        data = cls.check_json(json_dict)
+        instance = super(WithdrawalWebhook, cls).de_json(data)
+        instance.data = Withdrawal.de_json(instance.data)
+        return instance
+
+
+class UnknownWebhook(xRocketWebhook):
+    """Webhook whose type or invoice event is not known to this library.
+
+    xRocket may extend type and event values. This model retains the original
+    envelope instead of failing, so an application can log and ignore it.
+
+    :param id: Unique webhook delivery id, can be used by the receiver for idempotency.
+    :param timestamp: When webhook was sent.
+    :param type: Unknown webhook type, or ``invoice`` with an unknown event.
+    :param data: Original untyped webhook payload.
+    """
+
+
+def verify_webhook_signature(raw_body: bytes | bytearray | str, headers: Mapping[str, Any], webhook_secret: str) -> None:
+    """Verify the current xRocket Pay ``v1`` webhook signature.
+
+    API: https://docs.xrocket.exchange/api/pay/pay-api-overview
+
+    ``raw_body`` must be the original request body. ``bytes`` is preferred;
+    a string is accepted only when it is the unchanged request body text.
+    A parsed dictionary is intentionally rejected because serializing it again
+    can alter the signed representation.
+
+    :param raw_body: Original request body as bytes, bytearray, or unchanged
+        text.
+    :param headers: HTTP request headers. Header names are case-insensitive.
+    :param webhook_secret: Application webhook secret used as the HMAC key
+        without transformations.
+    :return: ``None`` when the signature is valid.
+    :raises xRocketWebhookUnsupportedVersionException: If
+        ``Signature-Version`` is not ``v1``.
+    :raises xRocketWebhookSignatureException: If a required header is absent,
+        arguments are invalid, or the signature does not match.
+    """
+    body = _get_raw_body(raw_body)
+    if not isinstance(headers, Mapping):
+        raise xRocketWebhookSignatureException("headers must be a mapping.")
+    if not isinstance(webhook_secret, str) or not webhook_secret:
+        raise xRocketWebhookSignatureException("webhook_secret must be a non-empty string.")
+
+    timestamp = _get_header(headers, "Signature-Timestamp")
+    version = _get_header(headers, "Signature-Version")
+    signature = _get_header(headers, "Signature")
+    if not timestamp or not version or not signature:
+        raise xRocketWebhookSignatureException(
+            "Webhook headers Signature-Timestamp, Signature-Version, and Signature are required."
+        )
+    if version != "v1":
+        raise xRocketWebhookUnsupportedVersionException(
+            "Unsupported xRocket webhook signature version: {}.".format(version)
+        )
+
+    signed_body = timestamp.encode("utf-8") + b"." + body
+    expected_signature = hmac.new(
+        webhook_secret.encode("utf-8"), signed_body, hashlib.sha256
+    ).hexdigest()
+    if not hmac.compare_digest(signature, expected_signature):
+        raise xRocketWebhookSignatureException("xRocket webhook signature does not match.")
+
+
+def parse_webhook(payload: bytes | bytearray | str | Mapping[str, Any]) -> xRocketWebhook:
+    """Parse an xRocket Pay webhook body into a typed model without verifying it.
+
+    API: https://docs.xrocket.exchange/api/pay/pay-api-overview
+
+    Use this only after independently calling :func:`verify_webhook_signature`.
+    In normal HTTP handling, prefer :func:`parse_and_verify_webhook`.
+
+    :param payload: Original JSON body as bytes or text, or a parsed envelope
+        mapping when signature verification has already occurred.
+    :return: A typed webhook model, or ``UnknownWebhook`` for an unknown type or invoice event.
+    :raises xRocketWebhookParseException: If the body is invalid JSON or does
+        not have the required webhook envelope structure.
+    """
+    envelope = _get_envelope(payload)
+    _validate_envelope(envelope)
+
+    webhook_type = envelope["type"]
+    if webhook_type == "invoice":
+        return _parse_invoice_webhook(envelope)
+    if webhook_type == "cheque":
+        _require_mapping(envelope["data"], "data")
+        return ChequeWebhook.de_json(envelope)
+    if webhook_type == "payout":
+        _require_mapping(envelope["data"], "data")
+        return PayoutWebhook.de_json(envelope)
+    if webhook_type == "withdrawal":
+        _require_mapping(envelope["data"], "data")
+        return WithdrawalWebhook.de_json(envelope)
+    return UnknownWebhook.de_json(envelope)
+
+
+def parse_and_verify_webhook(
+    raw_body: bytes | bytearray | str,
+    headers: Mapping[str, Any],
+    webhook_secret: str,
+) -> xRocketWebhook:
+    """Verify and parse an xRocket Pay webhook in the safe order.
+
+    API: https://docs.xrocket.exchange/api/pay/pay-api-overview
+
+    The signature is verified against the unchanged request body before JSON
+    parsing. The returned event must be deduplicated by its ``id`` in the
+    application's persistent storage before an irreversible business action.
+
+    :param raw_body: Original request body as bytes, bytearray, or unchanged
+        text.
+    :param headers: HTTP request headers. Header names are case-insensitive.
+    :param webhook_secret: Application webhook secret used as the HMAC key without transformations.
+    :return: A typed webhook model, or ``UnknownWebhook`` for an unknown type or invoice event.
+    :raises xRocketWebhookSignatureException: If signature validation fails.
+    :raises xRocketWebhookParseException: If the verified body is invalid JSON
+        or does not have the required webhook envelope structure.
+    """
+    verify_webhook_signature(raw_body, headers, webhook_secret)
+    return parse_webhook(raw_body)
+
+
+def _get_raw_body(raw_body: bytes | bytearray | str) -> bytes:
+    """Return the unchanged request body as bytes for signature verification."""
+    if isinstance(raw_body, bytes):
+        return raw_body
+    if isinstance(raw_body, bytearray):
+        return bytes(raw_body)
+    if isinstance(raw_body, str):
+        return raw_body.encode("utf-8")
+    raise xRocketWebhookSignatureException(
+        "raw_body must be bytes, bytearray, or unchanged request body text."
+    )
+
+
+def _get_header(headers: Mapping[str, Any], expected_name: str) -> str | None:
+    """Read one HTTP header without relying on a framework's header type."""
+    expected_name = expected_name.lower()
+    for name, value in headers.items():
+        if str(name).lower() == expected_name:
+            return str(value)
+    return None
+
+
+def _get_envelope(payload: bytes | bytearray | str | Mapping[str, Any]) -> dict[str, Any]:
+    """Decode a JSON webhook body or make a shallow copy of a mapping."""
+    if isinstance(payload, Mapping):
+        return dict(payload)
+    if isinstance(payload, bytearray):
+        payload = bytes(payload)
+    if isinstance(payload, bytes):
+        try:
+            payload = payload.decode("utf-8")
+        except UnicodeDecodeError as error:
+            raise xRocketWebhookParseException("Webhook body is not UTF-8 JSON.") from error
+    if isinstance(payload, str):
+        try:
+            payload = json.loads(payload)
+        except json.JSONDecodeError as error:
+            raise xRocketWebhookParseException("Webhook body is not valid JSON.") from error
+    if not isinstance(payload, Mapping):
+        raise xRocketWebhookParseException("Webhook body must contain a JSON object.")
+    return dict(payload)
+
+
+def _validate_envelope(envelope: Mapping[str, Any]) -> None:
+    """Validate the fields required by every documented webhook envelope."""
+    for field in ("id", "timestamp", "type", "data"):
+        if field not in envelope:
+            raise xRocketWebhookParseException(
+                "Webhook body is missing required field: {}.".format(field)
+            )
+    if not isinstance(envelope["type"], str):
+        raise xRocketWebhookParseException("Webhook field type must be a string.")
+
+
+def _parse_invoice_webhook(envelope: dict[str, Any]) -> xRocketWebhook:
+    """Choose the typed invoice webhook model using the nested event field."""
+    data = _require_mapping(envelope["data"], "data")
+    event = data.get("event")
+    if event == "invoice_status_changed":
+        _require_mapping(data.get("invoice"), "data.invoice")
+        return InvoiceStatusChangedWebhook.de_json(envelope)
+    if event == "payment_status_changed":
+        _require_mapping(data.get("invoice"), "data.invoice")
+        _require_mapping(data.get("payment"), "data.payment")
+        return PaymentStatusChangedWebhook.de_json(envelope)
+    return UnknownWebhook.de_json(envelope)
+
+
+def _require_mapping(value: Any, field_name: str) -> Mapping[str, Any]:
+    """Return a payload object or raise a precise structural parse error."""
+    if not isinstance(value, Mapping):
+        raise xRocketWebhookParseException(
+            "Webhook field {} must be a JSON object.".format(field_name)
+        )
+    return value

{pyxrocketapi-0.1.0 → pyxrocketapi-0.2.0}/pyXRocketAPI.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyXRocketAPI
-Version: 0.1.0
+Version: 0.2.0
 Summary: Python client for the xRocket Pay API
 Author: Badiboy
 License-Expression: MIT
@@ -17,7 +17,11 @@ License-File: LICENSE
 Requires-Dist: requests>=2.28
 Dynamic: license-file
 
-# pyXRocketAPI
+[![PyPi Package Version](https://img.shields.io/pypi/v/pyXRocketAPI.svg)](https://pypi.python.org/pypi/pyXRocketAPI)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/pyXRocketAPI.svg)](https://pypi.python.org/pypi/pyXRocketAPI)
+[![PyPi downloads](https://img.shields.io/pypi/dm/pyXRocketAPI.svg)](https://pypi.org/project/pyXRocketAPI/)
+
+# <p align="center">pyXRocketAPI</p>
 
 **pyXRocketAPI** is a Python client for the [xRocket Pay API](https://docs.xrocket.exchange/api/pay/pay-api-overview). It supports application information, balances, invoices, cheques, payouts, withdrawals, currency rates, and health checks.
 

{pyxrocketapi-0.1.0 → pyxrocketapi-0.2.0}/pyXRocketAPI.egg-info/SOURCES.txt

@@ -6,9 +6,11 @@ pyXRocketAPI/api.py
 pyXRocketAPI/exceptions.py
 pyXRocketAPI/models.py
 pyXRocketAPI/version.py
+pyXRocketAPI/webhooks.py
 pyXRocketAPI.egg-info/PKG-INFO
 pyXRocketAPI.egg-info/SOURCES.txt
 pyXRocketAPI.egg-info/dependency_links.txt
 pyXRocketAPI.egg-info/requires.txt
 pyXRocketAPI.egg-info/top_level.txt
-tests/test_api.py
+tests/test_api.py
+tests/test_webhooks.py

pyxrocketapi-0.2.0/tests/test_webhooks.py

@@ -0,0 +1,105 @@
+import hashlib
+import hmac
+import json
+import unittest
+
+from pyXRocketAPI import (
+    Cheque,
+    ChequeWebhook,
+    Invoice,
+    Payout,
+    PayoutWebhook,
+    PaymentStatusChangedWebhook,
+    UnknownWebhook,
+    Withdrawal,
+    WithdrawalWebhook,
+    parse_and_verify_webhook,
+    parse_webhook,
+    xRocketWebhookParseException,
+    xRocketWebhookSignatureException,
+)
+from pyXRocketAPI.models import InvoicePayment
+
+
+WEBHOOK_SECRET = "webhook-secret"
+SIGNATURE_TIMESTAMP = "1735689600000"
+
+
+def signed_webhook(payload):
+    body = json.dumps(payload, separators=(",", ":")).encode("utf-8")
+    signature = hmac.new(
+        WEBHOOK_SECRET.encode("utf-8"),
+        SIGNATURE_TIMESTAMP.encode("utf-8") + b"." + body,
+        hashlib.sha256,
+    ).hexdigest()
+    return body, {
+        "signature-timestamp": SIGNATURE_TIMESTAMP,
+        "signature-version": "v1",
+        "signature": signature,
+    }
+
+
+class XRocketWebhookTests(unittest.TestCase):
+    def test_parses_and_verifies_payment_status_changed_webhook(self):
+        body, headers = signed_webhook({
+            "id": "delivery-1",
+            "timestamp": "2025-01-01T00:00:00.000Z",
+            "type": "invoice",
+            "data": {
+                "event": "payment_status_changed",
+                "invoice": {"id": "invoice-1", "status": "paid"},
+                "payment": {"id": "payment-1", "status": "paid", "finalizedAt": "2025-01-01T00:00:00.000Z"},
+            },
+        })
+
+        event = parse_and_verify_webhook(body, headers, WEBHOOK_SECRET)
+
+        self.assertIsInstance(event, PaymentStatusChangedWebhook)
+        self.assertEqual(event.id, "delivery-1")
+        self.assertIsInstance(event.data.invoice, Invoice)
+        self.assertIsInstance(event.data.payment, InvoicePayment)
+        self.assertEqual(event.data.payment.status, "paid")
+
+    def test_rejects_invalid_signature_before_parsing(self):
+        body, headers = signed_webhook({"id": "delivery-1", "timestamp": "now", "type": "payout", "data": {}})
+
+        with self.assertRaises(xRocketWebhookSignatureException):
+            parse_and_verify_webhook(body + b" ", headers, WEBHOOK_SECRET)
+
+    def test_returns_unknown_webhook_for_future_type_and_invoice_event(self):
+        future_type = parse_webhook({
+            "id": "delivery-1", "timestamp": "now", "type": "future_type", "data": {"value": 1},
+        })
+        future_invoice_event = parse_webhook({
+            "id": "delivery-2", "timestamp": "now", "type": "invoice", "data": {"event": "future_event"},
+        })
+
+        self.assertIsInstance(future_type, UnknownWebhook)
+        self.assertEqual(future_type.data, {"value": 1})
+        self.assertIsInstance(future_invoice_event, UnknownWebhook)
+        self.assertEqual(future_invoice_event.data["event"], "future_event")
+
+    def test_parses_other_documented_webhook_types(self):
+        cases = (
+            ("cheque", {"chequeId": "cheque-1"}, ChequeWebhook, Cheque),
+            ("payout", {"payoutId": "payout-1"}, PayoutWebhook, Payout),
+            ("withdrawal", {"withdrawalId": "withdrawal-1"}, WithdrawalWebhook, Withdrawal),
+        )
+
+        for webhook_type, data, webhook_class, data_class in cases:
+            with self.subTest(webhook_type=webhook_type):
+                event = parse_webhook({
+                    "id": "delivery-1", "timestamp": "now", "type": webhook_type, "data": data,
+                })
+                self.assertIsInstance(event, webhook_class)
+                self.assertIsInstance(event.data, data_class)
+
+    def test_rejects_malformed_webhook_envelope(self):
+        with self.assertRaises(xRocketWebhookParseException):
+            parse_webhook(b"not json")
+        with self.assertRaises(xRocketWebhookParseException):
+            parse_webhook({"id": "delivery-1", "timestamp": "now", "type": "payout"})
+
+
+if __name__ == "__main__":
+    unittest.main()