Merge pull request #91 from starkbank/feature/brcode-payment-rules

Add rules attribute to BrcodePayment resource

CHANGELOG.md

@@ -17,6 +17,8 @@ Given a version number MAJOR.MINOR.PATCH, increment:
 - picture and pictureType parameters to Workspace.update method
 - rules attribute to Transfer resource
 - Transfer.Rule sub-resource
+- rules attribute to BrcodePayment resource
+- BrcodePayment.Rule sub-resource
 ### Fixed
 - nested resource casting
 - starkbank.error import

README.md

@@ -532,7 +532,7 @@ You can query institutions registered by the Brazilian Central Bank for Pix and
 ```python
 import starkbank
 
-institution = starkbank.institution.query(search="stark")
+institutions = starkbank.institution.query(search="stark")
 
 for institution in institutions:
     print(institution)
@@ -991,7 +991,7 @@ print(log)
 
 ## Pay a BR Code
 
-Paying a BR Code is also simple. After extracting the BRCode encoded in the Pix QR Code, you can do the following:
+Paying a BR Code is also simple. After extracting the BR Code encoded in the Pix QR Code, you can do the following:
 
 ```python
 import starkbank
@@ -1003,13 +1003,19 @@ payments = starkbank.brcodepayment.create([
         scheduled="2020-03-13",
         description="this will be fast",
         tags=["pix", "qrcode"],
+        rules=[
+            starkbank.brcodepayment.Rule(
+              key="resendingLimit",  # Set maximum number of retries if Payment fails due to systemic issues at the receiver bank
+              value=5                # Our resending limit is 10 by default
+            ) 
+        ]
     )
 ])
 
 for payment in payments:
     print(payment)
 ```
-
+**Note**: You can also configure payment behavior according to its rules
 **Note**: Instead of using BrcodePayment objects, you can also pass each payment element in dictionary format
 
 ## Get a BR Code payment

starkbank/brcodepayment/__brcodepayment.py

@@ -1,4 +1,7 @@
 from ..utils import rest
+from .rule.__rule import Rule
+from .rule.__rule import _sub_resource as _rule_resource
+from starkcore.utils.api import from_api_json
 from starkcore.utils.resource import Resource
 from starkcore.utils.checks import check_datetime, check_date
 
@@ -18,6 +21,7 @@ class BrcodePayment(Resource):
     ## Parameters (optional):
     - scheduled [datetime.date, datetime.datetime or string, default now]: payment scheduled date or datetime. ex: datetime.datetime(2020, 3, 10, 15, 17, 3)
     - tags [list of strings, default None]: list of strings for tagging
+    - rule [list of BrcodePayment.Rule, default []]: list of BrcodePayment.Rule objects for modifying payment behavior. ex: [Rule(key="resendingLimit", value=5)]
     ## Attributes (return-only):
     - id [string, default None]: unique id returned when payment is created. ex: "5656565656565656"
     - name [string]: receiver name. ex: "Jon Snow"
@@ -29,19 +33,20 @@ class BrcodePayment(Resource):
     - created [datetime.datetime, default None]: creation datetime for the payment. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0)
     """
 
-    def __init__(self, brcode, tax_id, description, amount=None, scheduled=None, tags=None, id=None, name=None,
+    def __init__(self, brcode, tax_id, description, amount=None, scheduled=None, tags=None, rules=None, id=None, name=None,
                  status=None, type=None, transaction_ids=None, fee=None, updated=None, created=None):
         Resource.__init__(self, id=id)
 
         self.brcode = brcode
         self.tax_id = tax_id
         self.description = description
-        self.tags = tags
+        self.amount = amount
         self.scheduled = check_date(scheduled)
+        self.tags = tags
+        self.rules = _parse_rules(rules)
         self.name = name
         self.status = status
         self.type = type
-        self.amount = amount
         self.transaction_ids = transaction_ids
         self.fee = fee
         self.updated = check_datetime(updated)
@@ -51,6 +56,18 @@ def __init__(self, brcode, tax_id, description, amount=None, scheduled=None, tag
 _resource = {"class": BrcodePayment, "name": "BrcodePayment"}
 
 
+def _parse_rules(rules):
+    if rules is None:
+        return None
+    parsed_rules = []
+    for rule in rules:
+        if isinstance(rule, Rule):
+            parsed_rules.append(rule)
+            continue
+        parsed_rules.append(from_api_json(_rule_resource, rule))
+    return parsed_rules
+
+
 def create(payments, user=None):
     """# Create BrcodePayments
     Send a list of BrcodePayment objects for creation in the Stark Bank API

starkbank/brcodepayment/__init__.py

@@ -1,3 +1,4 @@
 from .__brcodepayment import create, get, query, page, pdf, update
 from .log.__log import Log
 from . import log
+from .rule.__rule import Rule

starkbank/brcodepayment/rule/__rule.py

@@ -0,0 +1,17 @@
+from starkcore.utils.subresource import SubResource
+
+
+class Rule(SubResource):
+    """# BrcodePayment.Rule object
+    The BrcodePayment.Rule object modifies the behavior of BrcodePayment objects when passed as an argument upon their creation.
+    ## Parameters (required):
+    - key [string]: Rule to be customized, describes what BrcodePayment behavior will be altered. ex: "resendingLimit"
+    - value [integer]: Value of the rule. ex: 5
+    """
+
+    def __init__(self, key, value):
+        self.key = key
+        self.value = value
+
+
+_sub_resource = {"class": Rule, "name": "Rule"}

tests/api/testTransaction.py

@@ -91,3 +91,4 @@ def test_success(self):
 
 if __name__ == '__main__':
     main()
+

tests/sdk/testBrcodePayment.py

@@ -13,7 +13,10 @@ def test_success(self):
         payments = generateExampleBrcodePaymentsJson(n=5, next_day=True)
         payments = starkbank.brcodepayment.create(payments)
         for payment in payments:
-            print(payment)
+            self.assertIsNotNone(payment.id)
+            for rule in payment.rules:
+                if rule.key == "resendingLimit":
+                    self.assertIsNotNone(rule.value)
 
 
 class TestBrcodePaymentQuery(TestCase):

tests/sdk/testTransaction.py

@@ -50,7 +50,6 @@ def test_success(self):
         self.assertTrue(len(transactionIds) == 4)
 
 
-
 class TestTransactionInfoGet(TestCase):
 
     def test_success(self):

tests/utils/brcodePayment.py

@@ -1,9 +1,10 @@
 from copy import deepcopy
-from random import choice
+from random import choice, randint
 from hashlib import sha256
 from datetime import date, timedelta
 import starkbank
 from starkbank import BrcodePayment
+from starkbank.brcodepayment import Rule
 from .invoice import generateExampleInvoicesJson
 
 
@@ -25,6 +26,12 @@ def generateExampleBrcodePaymentsJson(n=1, next_day=False):
         payment = deepcopy(example_payment)
         payment.brcode = invoice.brcode
         payment.scheduled = min((date.today() + timedelta(days=1)) if next_day else date.today(), (invoice.due - timedelta(hours=3)).date())
+        payment.rules = [
+            Rule(
+                key="resendingLimit",
+                value=randint(0, 10)
+            )
+        ]
         payment.description = sha256(str(invoice.id).encode('utf-8')).hexdigest()
         payments.append(payment)
     return payments