python-terminusgps 23.0.0__py3-none-any.whl → 24.0.0__py3-none-any.whl

{python_terminusgps-23.0.0.dist-info → python_terminusgps-24.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-terminusgps
-Version: 23.0.0
+Version: 24.0.0
 Summary: Provides abstractions/utilities for working with Wialon API, Authorize.NET API, AWS API, and more.
 Project-URL: Documentation, https://app.terminusgps.com/docs/apps/python-terminusgps/index.html
 Project-URL: Repository, https://github.com/terminusgps/python-terminusgps

{python_terminusgps-23.0.0.dist-info → python_terminusgps-24.0.0.dist-info}/RECORD

@@ -1,14 +1,16 @@
 terminusgps/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 terminusgps/settings.py,sha256=UBj2tvuBzQDEz05PeFqHG4_ise3Bl6Iu7pxcrtjNaYE,568
-terminusgps/authorizenet/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-terminusgps/authorizenet/auth.py,sha256=l3sPpLycqVO-gppU2sH7YAScuHmm3xXylxW6Gdu6a7Q,563
-terminusgps/authorizenet/subscriptions.py,sha256=W2oIb1oWXEhtET4bHpUWzuLIl3XbAqMkghAXy0AyWAQ,1366
-terminusgps/authorizenet/utils.py,sha256=q8ReDcYIk2eG6d36IM1vZorfeAxKhyQRLdtrIpKTNwA,2212
+terminusgps/authorizenet/__init__.py,sha256=LiGLlWNNiqS7RSOP4Apabx-b9EBYyNbxRY_a0mvJoaE,466
+terminusgps/authorizenet/auth.py,sha256=ICxPPzoUc64VbsIIemEWKrn8xjHGwbNdo2VbtaFCFss,1107
+terminusgps/authorizenet/errors.py,sha256=HG5NwVxQCtOYidVl30y49PC0Ovw5VYdsy9wTgUFMw9M,949
+terminusgps/authorizenet/utils.py,sha256=5aczO2EcMX2bi-kRg8_fnzLzE7qMA9K1qBxAo2AJz1c,2021
 terminusgps/authorizenet/profiles/__init__.py,sha256=QKjMKcXpCSCEhv6LBCz0yGP8t0VxAyKyYRS4_HLYnxQ,114
-terminusgps/authorizenet/profiles/addresses.py,sha256=xAiqETexGXicYOd_M3a4SBuHweeZPDlfWhtpqdvls-g,5466
-terminusgps/authorizenet/profiles/base.py,sha256=UTudVCju5-pLJQwoK0IfuT8OvxZVJCX3vApveUY3XE4,2286
-terminusgps/authorizenet/profiles/customers.py,sha256=ehtsWhPt0zF8_3dFlgFBWHA4NbQb-6AvOhtjTy3uQDg,8639
-terminusgps/authorizenet/profiles/payments.py,sha256=jcF_uJcaeU2JR5Sqza0LccsQGe9F-SUCjvg3o3QskIk,8808
+terminusgps/authorizenet/profiles/addresses.py,sha256=uowUkrr4fa4g7pjgNDrjW0es5t_gH9B8VHI74PbTWFc,6303
+terminusgps/authorizenet/profiles/base.py,sha256=TOUHr22QRQBLErdysOkfcpJBusTjrUTqOmWEyNvMacA,2240
+terminusgps/authorizenet/profiles/customers.py,sha256=xe7LNsqSB_oRCY-teojDTt0O6a5yVf0dyuu86ftc4hA,8377
+terminusgps/authorizenet/profiles/payments.py,sha256=O_oZGUwO8XTApzr0itu-1XQYnWFR4gDpNCusWNzBh7A,11152
+terminusgps/authorizenet/subscriptions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+terminusgps/authorizenet/subscriptions/subscriptions.py,sha256=JQHo2FxQyRPJp1jlbD2mIt9RKEJZbADZcfozNTKWbz0,1514
 terminusgps/aws/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 terminusgps/aws/secrets.py,sha256=MxQEmmBLpMUQ2tYAsHdCYf-7RZ84LiogdKcTsACX5dw,361
 terminusgps/aws/ses.py,sha256=sDca2GjMaZvUt3kUPtGCpcqHiOkij9lMV1ogZofgYUU,2372
@@ -28,7 +30,7 @@ terminusgps/wialon/items/route.py,sha256=PTJx1gmT_PGz7nlSSUS2VzjYD-aAuvkEOIdIFne
 terminusgps/wialon/items/unit.py,sha256=-jQL5Alvz77FZWteYNM9VNX15jtCufI-DWRRj3hRsgA,8539
 terminusgps/wialon/items/unit_group.py,sha256=vGVJMBY1BrKK0tP-C1DCIz4Bh6P-HKRnKY1g8g95UIs,5031
 terminusgps/wialon/items/user.py,sha256=INwAibQVmjNNelepQXMfDevgJqMvIjHHgEjAMLRvhB0,7082
-python_terminusgps-23.0.0.dist-info/METADATA,sha256=mWo-bctKKFZdbhH0ROVcDsqvN9kC58jMl1o49TQkFCI,946
-python_terminusgps-23.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-python_terminusgps-23.0.0.dist-info/licenses/COPYING,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-python_terminusgps-23.0.0.dist-info/RECORD,,
+python_terminusgps-24.0.0.dist-info/METADATA,sha256=QU-Do0pVNWwhy5D08Y5-n2nKz_mknj6sQMRHgHWpf5s,946
+python_terminusgps-24.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+python_terminusgps-24.0.0.dist-info/licenses/COPYING,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+python_terminusgps-24.0.0.dist-info/RECORD,,

terminusgps/authorizenet/__init__.py

@@ -0,0 +1,9 @@
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+
+if not hasattr(settings, "DEBUG"):
+    raise ImproperlyConfigured("'DEBUG' setting is required.")
+if not hasattr(settings, "MERCHANT_AUTH_LOGIN_ID"):
+    raise ImproperlyConfigured("'MERCHANT_AUTH_LOGIN_ID' setting is required.")
+if not hasattr(settings, "MERCHANT_AUTH_TRANSACTION_KEY"):
+    raise ImproperlyConfigured("'MERCHANT_AUTH_TRANSACTION_KEY' setting is required.")

terminusgps/authorizenet/auth.py

@@ -4,6 +4,13 @@ from django.conf import settings
 
 
 def get_merchant_auth() -> merchantAuthenticationType:
+    """
+    Returns the merchant authentication information for Authorizenet API requests.
+
+    :returns: A merchant authentication object.
+    :rtype: :py:obj:`~authorizenet.apicontractsv1.merchantAuthenticationType`
+
+    """
     return merchantAuthenticationType(
         name=str(settings.MERCHANT_AUTH_LOGIN_ID),
         transactionKey=str(settings.MERCHANT_AUTH_TRANSACTION_KEY),
@@ -11,8 +18,22 @@ def get_merchant_auth() -> merchantAuthenticationType:
 
 
 def get_environment() -> str:
+    """
+    Returns the environment for Authorizenet API requests.
+
+    :returns: An Authorizenet API environment string.
+    :rtype: :py:obj:`str`
+
+    """
     return constants.SANDBOX if settings.DEBUG else constants.PRODUCTION
 
 
 def get_validation_mode() -> str:
+    """
+    Returns the validation mode for Authorizenet API requests.
+
+    :returns: An Authorizenet API validation string.
+    :rtype: :py:obj:`str`
+
+    """
     return "testMode" if settings.DEBUG else "liveMode"

terminusgps/authorizenet/errors.py

@@ -0,0 +1,31 @@
+class ControllerExecutionError(Exception):
+    """Raised when an Authorizenet API controller fails to execute."""
+
+    def __init__(self, message: str, code: str, *args, **kwargs) -> None:
+        """
+        Sets :py:attr:`message` and :py:attr`code` for the exception.
+
+        :param message: An Authorizenet API error message.
+        :type message: :py:obj:`str`
+        :param code: An Authorizenet API error code.
+        :type code: :py:obj:`str`
+        :returns: Nothing.
+        :rtype: :py:obj:`None`
+
+        """
+        super().__init__(message, *args, **kwargs)
+        self._message = message
+        self._code = code
+
+    def __str__(self) -> str:
+        return f"{self.code}: {self.message}"
+
+    @property
+    def message(self) -> str:
+        """An Authorizenet API error message."""
+        return self._message
+
+    @property
+    def code(self) -> str:
+        """An Authorizenet API error code."""
+        return self._code

terminusgps/authorizenet/profiles/addresses.py

@@ -1,57 +1,62 @@
 from authorizenet import apicontractsv1, apicontrollers
 
-from terminusgps.authorizenet.profiles.base import AuthorizenetSubProfileBase
+from .base import AuthorizenetSubProfileBase
 
 
 class AddressProfile(AuthorizenetSubProfileBase):
     """An Authorizenet customer address profile."""
 
-    def create(self, shipping_addr: apicontractsv1.customerAddressType) -> int:
+    def create(self, address: apicontractsv1.customerAddressType) -> int:
         """
         Creates an Authorizenet address profile.
 
-        :param shipping_addr: An Authorizenet customer address.
-        :type shipping_addr: :py:obj:`~authorizenet.apicontractsv1.customerAddressType`
+        :param address: A customer address.
+        :type address: :py:obj:`~authorizenet.apicontractsv1.customerAddressType`
         :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
+        :raises ValueError: If the Authorizenet API response was not retrieved.
         :returns: A new address profile id.
         :rtype: :py:obj:`int`
 
         """
-        response = self._authorizenet_create_shipping_address(shipping_addr)
+        response = self._authorizenet_create_shipping_address(address)
+        if response is None:
+            raise ValueError("Failed to retrieve Authorizenet API response.")
         return int(response.customerAddressId)
 
-    def update(self, shipping_addr: apicontractsv1.customerAddressType) -> dict:
+    def update(self, address: apicontractsv1.customerAddressType) -> dict | None:
         """
         Updates the Authorizenet address profile.
 
-        :param shipping_addr: A customer shipping address.
-        :type shipping_addr: :py:obj:`~authorizenet.apicontractsv1.customerAddressType`
+        :param address: A customer shipping address.
+        :type address: :py:obj:`~authorizenet.apicontractsv1.customerAddressType`
         :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
-        :returns: An Authorizenet API response.
-        :rtype: :py:obj:`dict`
+        :returns: An Authorizenet API response, if any.
+        :rtype: :py:obj:`dict` | :py:obj:`None`
 
         """
-        return self._authorizenet_update_shipping_address(shipping_addr)
+        return self._authorizenet_update_shipping_address(address)
 
-    def delete(self) -> dict:
+    def delete(self) -> dict | None:
         """
         Deletes the Authorizenet address profile.
 
         :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
         :returns: An Authorizenet API response, if any.
-        :rtype: :py:obj:`dict`
+        :rtype: :py:obj:`dict` | :py:obj:`None`
 
         """
         return self._authorizenet_delete_shipping_address()
 
-    def _authorizenet_get_shipping_address(self) -> dict:
+    def _authorizenet_get_shipping_address(self) -> dict | None:
         """
         Executes a :py:obj:`~authorizenet.apicontractsv1.getCustomerShippingAddressRequest` using the Authorizenet API.
 
+        `getCustomerShippingAddressRequest <https://developer.authorize.net/api/reference/index.html#customer-profiles-get-customer-shipping-address>`_
+
         :raises AssertionError: If :py:attr:`id` wasn't set.
         :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
-        :returns: An Authorizenet API response.
-        :rtype: :py:obj:`dict`
+        :returns: An Authorizenet API response, if any.
+        :rtype: :py:obj:`dict` | :py:obj:`None`
 
         """
         assert self.id, "'id' was not set."
@@ -62,63 +67,67 @@ class AddressProfile(AuthorizenetSubProfileBase):
             customerAddressId=self.id,
         )
         controller = apicontrollers.getCustomerShippingAddressController(request)
-        response = self.execute_controller(controller)
-        return response
+        return self.execute_controller(controller)
 
     def _authorizenet_create_shipping_address(
-        self, addr: apicontractsv1.customerAddressType
-    ) -> dict:
+        self, address: apicontractsv1.customerAddressType
+    ) -> dict | None:
         """
         Executes a :py:obj:`~authorizenet.apicontractsv1.createCustomerShippingAddressRequest` using the Authorizenet API.
 
+        `createCustomerShippingAddressRequest <https://developer.authorize.net/api/reference/index.html#customer-profiles-create-customer-shipping-address>`_
+
         :raises AssertionError: If :py:attr:`id` wasn't set.
         :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
-        :returns: An Authorizenet API response.
-        :rtype: :py:obj:`dict`
+        :returns: An Authorizenet API response, if any.
+        :rtype: :py:obj:`dict` | :py:obj:`None`
 
         """
         request = apicontractsv1.createCustomerShippingAddressRequest(
             merchantAuthentication=self.merchantAuthentication,
             customerProfileId=self.customerProfileId,
-            address=addr,
+            address=address,
             defaultShippingAddress=self.default,
         )
         controller = apicontrollers.createCustomerShippingAddressController(request)
-        response = self.execute_controller(controller)
-        return response
+        return self.execute_controller(controller)
 
     def _authorizenet_update_shipping_address(
-        self, addr: apicontractsv1.customerAddressType
-    ) -> dict:
+        self, address: apicontractsv1.customerAddressType
+    ) -> dict | None:
         """
         Executes a :py:obj:`~authorizenet.apicontractsv1.updateCustomerShippingAddressRequest` using the Authorizenet API.
 
+        `updateCustomerShippingAddressRequest <https://developer.authorize.net/api/reference/index.html#customer-profiles-update-customer-shipping-address>`_
+
         :raises AssertionError: If :py:attr:`id` wasn't set.
         :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
-        :returns: An Authorizenet API response.
-        :rtype: :py:obj:`dict`
+        :returns: An Authorizenet API response, if any.
+        :rtype: :py:obj:`dict` | :py:obj:`None`
 
         """
         assert self.id, "'id' was not set."
 
-        addr.customerAddressId = self.id
+        address.customerAddressId = self.id
         request = apicontractsv1.updateCustomerShippingAddressRequest(
             merchantAuthentication=self.merchantAuthentication,
             customerProfileId=self.customerProfileId,
-            address=addr,
+            address=address,
             default=self.default,
         )
         controller = apicontrollers.updateCustomerShippingAddressController(request)
         return self.execute_controller(controller)
 
-    def _authorizenet_delete_shipping_address(self) -> dict:
+    def _authorizenet_delete_shipping_address(self) -> dict | None:
         """
         Executes a :py:obj:`~authorizenet.apicontractsv1.deleteCustomerShippingAddressRequest` using the Authorizenet API.
 
+        `deleteCustomerShippingAddressRequest <https://developer.authorize.net/api/reference/index.html#customer-profiles-delete-customer-shipping-address>`_
+
         :raises AssertionError: If :py:attr:`id` wasn't set.
         :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
-        :returns: An Authorizenet API response.
-        :rtype: :py:obj:`dict`
+        :returns: An Authorizenet API response, if any.
+        :rtype: :py:obj:`dict` | :py:obj:`None`
 
         """
         assert self.id, "'id' was not set."
@@ -129,5 +138,4 @@ class AddressProfile(AuthorizenetSubProfileBase):
             customerAddressId=self.id,
         )
         controller = apicontrollers.deleteCustomerShippingAddressController(request)
-        response = self.execute_controller(controller)
-        return response
+        return self.execute_controller(controller)

terminusgps/authorizenet/profiles/base.py

@@ -3,8 +3,8 @@ from typing import override
 
 from authorizenet import apicontractsv1
 
-from terminusgps.authorizenet.auth import get_merchant_auth, get_validation_mode
-from terminusgps.authorizenet.utils import ControllerExecutionMixin
+from ..auth import get_merchant_auth, get_validation_mode
+from ..utils import ControllerExecutionMixin
 
 
 class AuthorizenetProfileBase(ControllerExecutionMixin):

terminusgps/authorizenet/profiles/customers.py

@@ -1,27 +1,30 @@
 from authorizenet import apicontractsv1, apicontrollers
 from authorizenet.apicontractsv1 import customerProfileType
 
-from terminusgps.authorizenet.profiles.base import AuthorizenetProfileBase
-from terminusgps.authorizenet.utils import get_customer_profile_ids
+from ..utils import ControllerExecutionError, get_customer_profile_ids
+from .base import AuthorizenetProfileBase
 
 
 class CustomerProfile(AuthorizenetProfileBase):
     """An Authorizenet customer profile."""
 
-    def create(self, email: str, desc: str | None = None) -> int:
+    def create(self, email: str, desc: str = "") -> int:
         """
-        Creates a customer profile using the Authorizenet API and returns its id.
+        Creates a customer profile and returns its id.
 
         :param email: An email address.
         :type email: :py:obj:`str`
         :param desc: An optional description.
-        :type desc: :py:obj:`str` | :py:obj:`None`
+        :type desc: :py:obj:`str`
         :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
+        :raises ValueError: If the Authorizenet API response was not retrieved.
         :returns: The new customer profile id.
         :rtype: :py:obj:`int`
 
         """
         response = self._authorizenet_create_customer_profile(email=email, desc=desc)
+        if response is None:
+            raise ValueError("Failed to retrieve Authorizenet API response.")
         return int(response.customerProfileId)
 
     def update(self, email: str, desc: str = "") -> None:
@@ -30,7 +33,7 @@ class CustomerProfile(AuthorizenetProfileBase):
 
         :param email: An email address.
         :type email: :py:obj:`str`
-        :param desc: An optional description. Default is ``""``
+        :param desc: An optional description.
         :type desc: :py:obj:`str`
         :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
         :returns: Nothing.
@@ -50,29 +53,23 @@ class CustomerProfile(AuthorizenetProfileBase):
         """
         self._authorizenet_delete_customer_profile()
 
-    def get_payment_profiles(self) -> list[dict] | None:
-        """
-        Returns a list of the customer's payment profiles.
-
-        :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
-        :returns: A list of customer payment profiles, if they exist.
-        :rtype: :py:obj:`list` | :py:obj:`None`
-
-        """
-        response = self._authorizenet_get_customer_profile(issuer_info=False)
-        return response.get("paymentProfiles") if response else None
-
-    def get_addresses(self) -> list[dict] | None:
-        """
-        Returns a list of the customer's address profiles.
-
-        :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
-        :returns: A list of customer shipping addresses, if they exist.
-        :rtype: :py:obj:`list` | :py:obj:`None`
+    @property
+    def payment_profiles(self) -> list[dict] | None:
+        """A list of the customer's payment profiles, if any."""
+        try:
+            response = self._authorizenet_get_customer_profile(issuer_info=False)
+            return response.get("paymentProfiles") if response else None
+        except ControllerExecutionError:
+            return
 
-        """
-        response = self._authorizenet_get_customer_profile(issuer_info=False)
-        return response.get("shipToList") if response else None
+    @property
+    def address_profiles(self) -> list[dict] | None:
+        """A list of the customer's address profiles, if any."""
+        try:
+            response = self._authorizenet_get_customer_profile(issuer_info=False)
+            return response.get("shipToList") if response else None
+        except ControllerExecutionError:
+            return
 
     @property
     def exists(self) -> bool:
@@ -109,7 +106,6 @@ class CustomerProfile(AuthorizenetProfileBase):
         :type email: :py:obj:`str`
         :param desc: An optional description.
         :type desc: :py:obj:`str`
-        :raises AssertionError: If :py:attr:`id` wasn't set.
         :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
         :returns: An Authorizenet API response, if any.
         :rtype: :py:obj:`dict` | :py:obj:`None`

terminusgps/authorizenet/profiles/payments.py

@@ -1,6 +1,6 @@
 from authorizenet import apicontractsv1, apicontrollers
 
-from terminusgps.authorizenet.profiles.base import AuthorizenetSubProfileBase
+from .base import AuthorizenetSubProfileBase
 
 
 class PaymentProfile(AuthorizenetSubProfileBase):
@@ -8,36 +8,58 @@ class PaymentProfile(AuthorizenetSubProfileBase):
 
     def create(
         self,
-        billing_addr: apicontractsv1.customerAddressType,
+        address: apicontractsv1.customerAddressType,
         payment: apicontractsv1.paymentType,
     ) -> int:
         """
         Creates an Authorizenet payment profile and returns its id.
 
-        :param billing_addr: A billing address.
-        :type billing_addr: :py:obj:`~authorizenet.apicontractsv1.customerAddressType`
+        :param address: A billing address.
+        :type address: :py:obj:`~authorizenet.apicontractsv1.customerAddressType`
         :param payment: A payment object.
         :type payment: :py:obj:`~authorizenet.apicontractsv1.paymentType`
+        :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
+        :raises ValueError: If the Authorizenet API response was not retrieved.
         :returns: The new payment profile's id.
         :rtype: :py:obj:`int`
 
         """
-        response = self._authorizenet_create_payment_profile(billing_addr, payment)
+        response = self._authorizenet_create_payment_profile(address, payment)
+        if response is None:
+            raise ValueError("Failed to retrieve Authorizenet API response.")
         return int(response.customerPaymentProfileId)
 
     def update(
         self,
-        billing_addr: apicontractsv1.customerAddressType,
+        address: apicontractsv1.customerAddressType,
         payment: apicontractsv1.paymentType,
-    ) -> dict:
-        """Updates the Authorizenet payment profile."""
-        return self._authorizenet_update_payment_profile(billing_addr, payment)
+    ) -> dict | None:
+        """
+        Updates the Authorizenet payment profile.
+
+        :param address: A billing address.
+        :type address: :py:obj:`~authorizenet.apicontractsv1.customerAddressType`
+        :param payment: A payment method.
+        :type payment: :py:obj:`~authorizenet.apicontractsv1.paymentType`
+        :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
+        :returns: An Authorizenet API reponse, if any.
+        :rtype: :py:obj:`dict` | :py:obj:`None`
+
+        """
+        return self._authorizenet_update_payment_profile(address, payment)
 
-    def delete(self) -> dict:
-        """Deletes the Authorizenet payment profile."""
+    def delete(self) -> dict | None:
+        """
+        Deletes the Authorizenet payment profile.
+
+        :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
+        :returns: An Authorizenet API response, if any.
+        :rtype: :py:obj:`dict` | :py:obj:`None`
+
+        """
         return self._authorizenet_delete_payment_profile()
 
-    def get_details(self, issuer_info: bool = False) -> dict:
+    def get_details(self, issuer_info: bool = False) -> dict | None:
         return self._authorizenet_get_payment_profile(issuer_info)
 
     def _authorizenet_get_transaction_list_for_customer(
@@ -46,10 +68,12 @@ class PaymentProfile(AuthorizenetSubProfileBase):
         ordering: str = "submitTimeUTC",
         offset: int = 1,
         descending: bool = False,
-    ) -> dict:
+    ) -> dict | None:
         """
         Executes a :py:obj:`~authorizenet.apicontractsv1.getTransactionListForCustomerRequest` using the Authorizenet API.
 
+        `getTransactionListForCustomerRequest <https://developer.authorize.net/api/reference/index.html#transaction-reporting-get-transaction-list>`_
+
         :param limit: Total number of transactions to retrieve. Default is ``100``.
         :type limit: :py:obj:`int`
         :param ordering: A field to order the transactions by. Default is ``"submitTimeUTC"``.
@@ -60,8 +84,9 @@ class PaymentProfile(AuthorizenetSubProfileBase):
         :type descending: :py:obj:`bool`
         :raises ValueError: If ``ordering`` is invalid.
         :raises AssertionError: If :py:attr:`id` wasn't set.
-        :returns: An Authorizenet API response.
-        :rtype: :py:obj:`dict`
+        :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
+        :returns: An Authorizenet API response, if any.
+        :rtype: :py:obj:`dict` | :py:obj:`None`
 
         """
         ordering_options: tuple[str, str] = ("id", "submitTimeUTC")
@@ -78,52 +103,55 @@ class PaymentProfile(AuthorizenetSubProfileBase):
             paging={"limit": str(limit), "offset": str(offset)},
         )
         controller = apicontrollers.getTransactionListForCustomerController(request)
-        response = self.execute_controller(controller)
-        return response
+        return self.execute_controller(controller)
 
     def _authorizenet_create_payment_profile(
         self,
-        billing_addr: apicontractsv1.customerAddressType,
+        address: apicontractsv1.customerAddressType,
         payment: apicontractsv1.paymentType,
-    ) -> dict:
+    ) -> dict | None:
         """
         Executes a :py:obj:`~authorizenet.apicontractsv1.createCustomerPaymentProfileRequest` using the Authorizenet API.
 
-        :param billing_addr: A customer address.
-        :type billing_addr: :py:obj:`~authorizenet.apicontractsv1.customerAddressType`
+        `createCustomerPaymentProfileRequest <https://developer.authorize.net/api/reference/index.html#customer-profiles-create-customer-payment-profile>`_
+
+        :param address: A billing address.
+        :type address: :py:obj:`~authorizenet.apicontractsv1.customerAddressType`
         :param payment: A payment method.
         :type payment: :py:obj:`~authorizenet.apicontractsv1.paymentType`
-        :raises AssertionError: If :py:attr:`id` wasn't set.
-        :raises : If :py:attr:`id` wasn't set.
-        :returns: An Authorizenet API response.
-        :rtype: :py:obj:`dict`
+        :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
+        :returns: An Authorizenet API response, if any.
+        :rtype: :py:obj:`dict` | :py:obj:`None`
 
         """
         request = apicontractsv1.createCustomerPaymentProfileRequest(
             customerProfileId=self.customerProfileId,
             merchantAuthentication=self.merchantAuthentication,
             paymentProfile=apicontractsv1.customerPaymentProfileType(
-                billTo=billing_addr, payment=payment, defaultPaymentProfile=self.default
+                billTo=address, payment=payment, defaultPaymentProfile=self.default
             ),
             validationMode=self.validationMode,
         )
         controller = apicontrollers.createCustomerPaymentProfileController(request)
-        response = self.execute_controller(controller)
-        return response
+        return self.execute_controller(controller)
 
-    def _authorizenet_get_payment_profile(self, issuer_info: bool = False) -> dict:
+    def _authorizenet_get_payment_profile(
+        self, issuer_info: bool = False
+    ) -> dict | None:
         """
         Executes a :py:obj:`~authorizenet.apicontractsv1.getCustomerPaymentProfileRequest` using the Authorizenet API.
 
+        `getCustomerPaymentProfileRequest <https://developer.authorize.net/api/reference/index.html#customer-profiles-get-customer-payment-profile>`_
+
         :param issuer_info: Whether or not to include issuer information in the response.
         :type issuer_info: :py:obj:`bool`
         :raises AssertionError: If :py:attr:`id` wasn't set.
-        :returns: An Authorizenet API response.
-        :rtype: :py:obj:`dict`
+        :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
+        :returns: An Authorizenet API response, if any.
+        :rtype: :py:obj:`dict` | :py:obj:`None`
 
         """
         assert self.id, "'id' was not set."
-
         request = apicontractsv1.getCustomerPaymentProfileRequest(
             merchantAuthentication=self.merchantAuthentication,
             customerProfileId=self.customerProfileId,
@@ -131,24 +159,26 @@ class PaymentProfile(AuthorizenetSubProfileBase):
             includeIssuerInfo=str(issuer_info).lower(),
         )
         controller = apicontrollers.getCustomerPaymentProfileController(request)
-        response = self.execute_controller(controller)
-        return response
+        return self.execute_controller(controller)
 
     def _authorizenet_update_payment_profile(
         self,
-        billing_addr: apicontractsv1.customerAddressType,
+        address: apicontractsv1.customerAddressType,
         payment: apicontractsv1.paymentType,
-    ) -> dict:
+    ) -> dict | None:
         """
-        Executes a :py:obj:`~authorizenet.apicontractsv1.validateCustomerPaymentProfileRequest` using the Authorizenet API.
+        Executes a :py:obj:`~authorizenet.apicontractsv1.updateCustomerPaymentProfileRequest` using the Authorizenet API.
 
-        :param billing_addr: A customer address.
-        :type billing_addr: :py:obj:`~authorizenet.apicontractsv1.customerAddressType`
+        `updateCustomerPaymentProfileRequest <https://developer.authorize.net/api/reference/index.html#customer-profiles-update-customer-payment-profile>`_
+
+        :param address: A customer address.
+        :type address: :py:obj:`~authorizenet.apicontractsv1.customerAddressType`
         :param payment: A payment method.
         :type payment: :py:obj:`~authorizenet.apicontractsv1.paymentType`
         :raises AssertionError: If :py:attr:`id` wasn't set.
-        :returns: An Authorizenet API response.
-        :rtype: :py:obj:`dict`
+        :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
+        :returns: An Authorizenet API response, if any.
+        :rtype: :py:obj:`dict` | :py:obj:`None`
 
         """
         assert self.id, "'id' was not set."
@@ -157,7 +187,7 @@ class PaymentProfile(AuthorizenetSubProfileBase):
             merchantAuthentication=self.merchantAuthentication,
             customerProfileId=self.customerProfileId,
             paymentProfile=apicontractsv1.customerPaymentProfileType(
-                billTo=billing_addr,
+                billTo=address,
                 payment=payment,
                 defaultPaymentProfile=self.default,
                 customerPaymentProfileId=self.id,
@@ -165,20 +195,22 @@ class PaymentProfile(AuthorizenetSubProfileBase):
             validationMode=self.validationMode,
         )
         controller = apicontrollers.updateCustomerPaymentProfileController(request)
-        response = self.execute_controller(controller)
-        return response
+        return self.execute_controller(controller)
 
-    def _authorizenet_validate_payment_profile(self) -> dict:
+    def _authorizenet_validate_payment_profile(self) -> dict | None:
         """
         Executes a :py:obj:`~authorizenet.apicontractsv1.validateCustomerPaymentProfileRequest` using the Authorizenet API.
 
+        `validateCustomerPaymentProfileRequest <https://developer.authorize.net/api/reference/index.html#customer-profiles-validate-customer-payment-profile>`_
+
         :raises AssertionError: If :py:attr:`id` wasn't set.
-        :returns: An Authorizenet API response.
-        :rtype: :py:obj:`dict`
+        :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
+        :returns: An Authorizenet API response, if any.
+        :rtype: :py:obj:`dict` | :py:obj:`None`
+
 
         """
         assert self.id, "'id' was not set."
-
         request = apicontractsv1.validateCustomerPaymentProfileRequest(
             merchantAuthentication=self.merchantAuthentication,
             customerProfileId=self.customerProfileId,
@@ -186,16 +218,18 @@ class PaymentProfile(AuthorizenetSubProfileBase):
             validationMode=self.validationMode,
         )
         controller = apicontrollers.validateCustomerPaymentProfileController(request)
-        response = self.execute_controller(controller)
-        return response
+        return self.execute_controller(controller)
 
-    def _authorizenet_delete_payment_profile(self) -> dict:
+    def _authorizenet_delete_payment_profile(self) -> dict | None:
         """
         Executes a :py:obj:`~authorizenet.apicontractsv1.deleteCustomerPaymentProfileRequest` using the Authorizenet API.
 
+        `deleteCustomerPaymentProfileRequest <https://developer.authorize.net/api/reference/index.html#customer-profiles-delete-customer-payment-profile>`_
+
         :raises AssertionError: If :py:attr:`id` wasn't set.
-        :returns: An Authorizenet API response.
-        :rtype: :py:obj:`dict`
+        :raises ControllerExecutionError: If something goes wrong during an Authorizenet API call.
+        :returns: An Authorizenet API response, if any.
+        :rtype: :py:obj:`dict` | :py:obj:`None`
 
         """
         assert self.id, "'id' was not set."
@@ -206,5 +240,4 @@ class PaymentProfile(AuthorizenetSubProfileBase):
             customerPaymentProfileId=self.id,
         )
         controller = apicontrollers.deleteCustomerPaymentProfileController(request)
-        response = self.execute_controller(controller)
-        return response
+        return self.execute_controller(controller)

terminusgps/authorizenet/{subscriptions.py → subscriptions/subscriptions.py}

@@ -1,12 +1,12 @@
 from authorizenet import apicontractsv1, apicontrollers
 
-from terminusgps.authorizenet.auth import get_merchant_auth
-from terminusgps.authorizenet.utils import ControllerExecutionMixin
+from ..auth import get_merchant_auth
+from ..utils import ControllerExecutionMixin
 
 
 class Subscription(ControllerExecutionMixin):
     def __init__(self, id: str | int | None = None, *args, **kwargs) -> None:
-        if id and isinstance(id, str) and not id.isdigit():
+        if id is not None and isinstance(id, str) and not id.isdigit():
             raise ValueError(f"'id' must be a digit, got '{id}'.")
         self.id = int(id) if id else self.create(*args, **kwargs)
 
@@ -15,8 +15,9 @@ class Subscription(ControllerExecutionMixin):
         name: str,
         amount: str,
         schedule: apicontractsv1.paymentScheduleType,
-        payment: apicontractsv1.paymentType,
-        address: apicontractsv1.customerAddressType,
+        profile_id: int | str,
+        payment_id: int | str,
+        address_id: int | str,
         trial_amount: str = "0.00",
     ) -> int:
         request = apicontractsv1.ARBCreateSubscriptionRequest(
@@ -26,8 +27,11 @@ class Subscription(ControllerExecutionMixin):
                 paymentSchedule=schedule,
                 amount=amount,
                 trialAmount=trial_amount,
-                payment=payment,
-                bill_to=address,
+                profile=apicontractsv1.customerProfileIdType(
+                    customerProfileId=str(profile_id),
+                    customerPaymentProfileId=str(payment_id),
+                    customerAddressId=str(address_id),
+                ),
             ),
         )
         controller = apicontrollers.ARBCreateSubscriptionController(request)

terminusgps/authorizenet/utils.py

@@ -2,17 +2,7 @@ from authorizenet import apicontractsv1, apicontrollers
 from authorizenet.apicontrollersbase import APIOperationBase
 
 from .auth import get_environment, get_merchant_auth
-
-
-class ControllerExecutionError(Exception):
-    """Raised when an Authorizenet API controller fails to execute."""
-
-    def __init__(self, message: str, code: str, *args, **kwargs) -> None:
-        self.code = code
-        super().__init__(message, *args, **kwargs)
-
-    def __str__(self) -> str:
-        return f"{self.code}: {self.message}"
+from .errors import ControllerExecutionError
 
 
 class ControllerExecutionMixin:
@@ -57,5 +47,8 @@ def get_customer_profile_ids() -> list[int]:
     response = controller.getresponse()
 
     if response is not None and response.messages.resultCode != "Ok":
-        raise ValueError(response.messages.message["text"].text)
+        raise ControllerExecutionError(
+            message=response.messages.message[0]["text"].text,
+            code=response.messages.message[0]["code"].text,
+        )
     return [int(id) for id in response.ids.getchildren()]