SP-527 Make Python SDK at parity with API

Author: mwarzybok-sumoheavy

src/bitpay/client.py

@@ -24,6 +24,7 @@
 from .environment import Environment
 from .models.facade import Facade
 from .models.bill.bill import Bill
+from .models.invoice.invoice_event_token import InvoiceEventToken
 from .models.rate.rate import Rate
 from .utils.guid_generator import GuidGenerator
 from .models.rate.rates import Rates
@@ -184,6 +185,25 @@ def get_invoice(
         client = self.create_invoice_client()
         return client.get(invoice_id, facade, sign_request)
 
+    def get_invoice_by_guid(
+        self, guid: str, facade: str = Facade.MERCHANT, sign_request: bool = True
+    ) -> Invoice:
+        """
+        Retrieve a BitPay invoice by invoice id using the specified facade.
+        The client must have been previously authorized for the specified
+        facade (the public facade requires no authorization)
+
+        :param str guid: The id of the invoice to retrieve
+        :param str facade: The facade used to create it
+        :param bool sign_request: Signed request
+        :return: A BitPay Invoice object
+        :rtype: Invoice
+        :raises BitPayException
+        :raises InvoiceQueryException
+        """
+        client = self.create_invoice_client()
+        return client.get_by_guid(guid, facade, sign_request)
+
     def get_invoices(
         self,
         date_start: str,
@@ -213,6 +233,21 @@ def get_invoices(
             date_start, date_end, status, order_id, limit, offset
         )
 
+    def get_invoice_event_token(self, invoice_id: str) -> InvoiceEventToken:
+        """
+        Retrieves a bus token which can be used to subscribe to invoice events.
+
+        :param str invoice_id: The id of the invoice for which you want to fetch an event token.
+        :return: Invoice Event Token.
+        :rtype: InvoiceEventToken
+        :raises BitPayException
+        :raises InvoiceQueryException
+        """
+        client = self.create_invoice_client()
+        return client.get_event_token(
+            invoice_id
+        )
+
     def update_invoice(
         self,
         invoice_id: str,
@@ -250,6 +285,21 @@ def cancel_invoice(self, invoice_id: str, force_cancel: bool = False) -> Invoice
         client = self.create_invoice_client()
         return client.cancel(invoice_id, force_cancel)
 
+    def cancel_invoice_by_guid(self, guid: str, force_cancel: bool = False) -> Invoice:
+        """
+        Delete a previously created BitPay invoice.
+
+        :param str guid: The GUID of the BitPay invoice to be canceled.
+        :param bool force_cancel: Query param that will cancel the invoice even if
+        no contact information is present
+        :return: A BitPay generated Invoice object.
+        :rtype: Invoice
+        :raises BitPayException
+        :raises InvoiceCancellationException
+        """
+        client = self.create_invoice_client()
+        return client.cancel_by_guid(guid, force_cancel)
+
     def pay_invoice(self, invoice_id: str, complete: bool = True) -> Invoice:
         """
         Pay an invoice with a mock transaction - it works only for test environment.
@@ -285,6 +335,7 @@ def create_refund(
         immediate: bool = False,
         buyer_pays_refund_fee: bool = False,
         reference: str = None,
+        guid: str = None
     ) -> Refund:
         """
         Create a refund for a BitPay invoice.
@@ -300,14 +351,16 @@ def create_refund(
         :param str reference: Present only if specified in the request to create the refund.
         This is your reference label for this refund. It will be passed-through on each response for you to identify
         the refund in your system. Maximum string length is 100 characters.
+        :param str guid: Variable provided by the merchant and designed to be used by the merchant
+        to correlate the refund with a refund ID in their system.
         :return: An updated Refund Object
         :rtype: Refund
         :raises BitPayException
         :raises RefundCreationException
         """
         client = self.create_refund_client()
         return client.create(
-            invoice_id, amount, preview, immediate, buyer_pays_refund_fee, reference
+            invoice_id, amount, preview, immediate, buyer_pays_refund_fee, reference, guid
         )
 
     def get_refund(self, refund_id: str) -> Refund:
@@ -323,6 +376,19 @@ def get_refund(self, refund_id: str) -> Refund:
         client = self.create_refund_client()
         return client.get(refund_id)
 
+    def get_refund_by_guid(self, guid: str) -> Refund:
+        """
+        Retrieve a previously made refund request on a BitPay invoice.
+
+        :param str guid: The BitPay refund GUID.
+        :return: BitPay Refund object with the associated Refund object.
+        :rtype: Refund
+        :raises BitPayException
+        :raises RefundQueryException
+        """
+        client = self.create_refund_client()
+        return client.get_by_guid(guid)
+
     def get_refunds(self, invoice_id: str) -> List[Refund]:
         """
         Retrieve all refund requests on a BitPay invoice.
@@ -350,6 +416,20 @@ def update_refund(self, refund_id: str, status: str) -> Refund:
         client = self.create_refund_client()
         return client.update(refund_id, status)
 
+    def update_refund_by_guid(self, refund_guid: str, status: str) -> Refund:
+        """
+        Update the status of a BitPay invoice refund.
+
+        :param str refund_guid: BitPay refund GUID.
+        :param str status: The new status for the refund to be updated
+        :return: A BitPay generated Refund object.
+        :rtype: Refund
+        :raises BitPayException
+        :raises RefundUpdateException
+        """
+        client = self.create_refund_client()
+        return client.update_by_guid(refund_guid, status)
+
     def cancel_refund(self, refund_id: str) -> Refund:
         """
         Cancel a previously submitted refund request on a BitPay invoice.
@@ -363,6 +443,19 @@ def cancel_refund(self, refund_id: str) -> Refund:
         client = self.create_refund_client()
         return client.cancel(refund_id)
 
+    def cancel_refund_by_guid(self, guid: str) -> Refund:
+        """
+        Cancel a previously submitted refund request on a BitPay invoice.
+
+        :param str guid: The refund GUID for the refund to be canceled.
+        :return: Cancelled refund Object.
+        :rtype: Refund
+        :raises BitPayException
+        :raises RefundCancellationException
+        """
+        client = self.create_refund_client()
+        return client.cancel_by_guid(guid)
+
     def request_refund_notification(self, refund_id: str) -> bool:
         """
         Send a refund notification.

src/bitpay/client/invoice_client.py

@@ -14,6 +14,7 @@
 from bitpay.exceptions.invoice_update_exception import InvoiceUpdateException
 from bitpay.models.facade import Facade
 from bitpay.models.invoice.invoice import Invoice
+from bitpay.models.invoice.invoice_event_token import InvoiceEventToken
 from bitpay.utils.guid_generator import GuidGenerator
 from bitpay.utils.token_container import TokenContainer
 
@@ -48,6 +49,9 @@ def create(
         :raises InvoiceCreationException
         """
         try:
+            if invoice.get_guid() is None:
+                invoice.set_guid(self.__guid_generator.execute())
+
             invoice.set_token(self.__token_container.get_access_token(facade))
             invoice_json = invoice.to_json()
             response_json = self.__bitpay_client.post(
@@ -114,6 +118,47 @@ def get(
 
         return invoice
 
+    def get_by_guid(
+        self, guid: str, facade: str = Facade.MERCHANT, sign_request: bool = True
+    ) -> Invoice:
+        """
+        Retrieve a BitPay invoice by invoice id using the specified facade.
+        The client must have been previously authorized for the specified
+        facade (the public facade requires no authorization)
+
+        :param str guid: The GUID of the invoice to retrieve
+        :param str facade: The facade used to create it
+        :param bool sign_request: Signed request
+        :return: A BitPay Invoice object
+        :rtype: Invoice
+        :raises BitPayException
+        :raises InvoiceQueryException
+        """
+        try:
+            params = {"token": self.__token_container.get_access_token(facade)}
+            response_json = self.__bitpay_client.get(
+                "invoices/guid/%s" % guid, params, sign_request
+            )
+        except BitPayException as exe:
+            raise InvoiceQueryException(
+                "failed to serialize Invoice object : " "%s" % str(exe),
+                exe.get_api_code(),
+            )
+        except Exception as exe:
+            raise InvoiceQueryException(
+                "failed to serialize Invoice object :" " %s" % str(exe)
+            )
+
+        try:
+            invoice = Invoice(**response_json)
+        except Exception as exe:
+            raise InvoiceQueryException(
+                "failed to deserialize BitPay server response"
+                " (Invoice) : %s" % str(exe)
+            )
+
+        return invoice
+
     def get_invoices(
         self,
         date_start: str,
@@ -267,6 +312,78 @@ def cancel(self, invoice_id: str, force_cancel: bool = False) -> Invoice:
             )
         return invoice
 
+    def cancel_by_guid(self, guid, force_cancel) -> Invoice:
+        """
+        Delete a previously created BitPay invoice.
+
+        :param str guid: The GUID of the BitPay invoice to be canceled.
+        :param bool force_cancel: Query param that will cancel the invoice even if
+        no contact information is present
+        :return: A BitPay generated Invoice object.
+        :rtype: Invoice
+        :raises BitPayException
+        :raises InvoiceCancellationException
+        """
+        try:
+            params = {
+                "token": self.__token_container.get_access_token(Facade.MERCHANT),
+                "forceCancel": force_cancel,
+            }
+            response_json = self.__bitpay_client.delete(
+                "invoices/guid/%s" % guid, params
+            )
+        except BitPayException as exe:
+            raise InvoiceCancellationException(
+                "failed to serialize Invoice object : %s" % str(exe), exe.get_api_code()
+            )
+        except Exception as exe:
+            raise InvoiceCancellationException(
+                "failed to serialize Invoice object : %s" % str(exe)
+            )
+
+        try:
+            invoice = Invoice(**response_json)
+        except Exception as exe:
+            raise InvoiceCancellationException(
+                "failed to deserialize BitPay server"
+                " response (Invoice) : %s" % str(exe)
+            )
+        return invoice
+
+    def get_event_token(self, invoice_id: str) -> InvoiceEventToken:
+        """
+        Retrieves a bus token which can be used to subscribe to invoice events.
+
+        :param str invoice_id: The id of the invoice for which you want to fetch an event token.
+        :return: Invoice Event Token.
+        :rtype: InvoiceEventToken
+        :raises BitPayException
+        :raises InvoiceQueryException
+        """
+        try:
+            params = {
+                "token": self.__token_container.get_access_token(Facade.MERCHANT),
+            }
+            response_json = self.__bitpay_client.delete(
+                "invoices/%s/events" % invoice_id, params
+            )
+        except BitPayException as exe:
+            raise InvoiceCancellationException(
+                "failed to serialize Invoice object : %s" % str(exe), exe.get_api_code()
+            )
+        except Exception as exe:
+            raise InvoiceCancellationException(
+                "failed to serialize Invoice object : %s" % str(exe)
+            )
+
+        try:
+            return InvoiceEventToken(**response_json)
+        except Exception as exe:
+            raise InvoiceCancellationException(
+                "failed to deserialize BitPay server"
+                " response (Invoice) : %s" % str(exe)
+            )
+
     def pay(self, invoice_id: str, complete: bool = True) -> Invoice:
         """
         Pay an invoice with a mock transaction - it works only for test environment.

src/bitpay/client/payout_recipient_client.py

@@ -50,6 +50,9 @@ def submit(self, recipients: PayoutRecipients) -> List[PayoutRecipient]:
         :raises PayoutRecipientCreationException
         """
         try:
+            if recipients.get_guid() is None:
+                recipients.set_guid(self.__guid_generator.execute())
+
             recipients.set_token(self.__token_container.get_access_token(Facade.PAYOUT))
 
             response_json = self.__bitpay_client.post(