Merge pull request #36 from balanced/customers

Customers

Author: msherry

balanced/__init__.py

@@ -1,4 +1,4 @@
-__version__ = '0.10.0'
+__version__ = '0.10.2'
 from collections import defaultdict
 import contextlib
 
@@ -8,7 +8,7 @@
     Hold, Credit, Debit, Refund,
     Merchant, Transaction, BankAccount, Card,
     Callback, Event, EventCallback, EventCallbackLog,
-    BankAccountVerification,
+    BankAccountVerification, Customer,
 )
 from balanced import exc
 
@@ -31,6 +31,7 @@
     EventCallback.__name__,
     EventCallbackLog.__name__,
     BankAccountVerification.__name__,
+    Customer.__name__,
     exc.__name__.partition('.')[-1],
 ]
 

balanced/resources.py

@@ -7,7 +7,9 @@
 import iso8601
 
 from balanced.utils import cached_property, url_encode, classproperty
-from balanced.exc import NoResultFound, MultipleResultsFound, ResourceError
+from balanced.exc import (
+    NoResultFound, MultipleResultsFound, ResourceError, BalancedError,
+)
 
 
 LOGGER = logging.getLogger(__name__)
@@ -1163,6 +1165,147 @@ class Callback(Resource):
                                   resides_under_marketplace=True)
 
 
+class Customer(Resource):
+    """
+    A customer represents a business or person within your Marketplace. A
+    customer can have many funding instruments such as cards and bank accounts
+    associated to them.
+    """
+    __metaclass__ = resource_base(collection='customers',
+                                  resides_under_marketplace=False)
+
+    def add_card(self, card):
+        """
+        Associates the `Card` represented by `card` with this `Customer`.
+        """
+        if isinstance(card, basestring):
+            self.card_uri = card
+        elif hasattr(card, 'uri'):
+            self.card_uri = card.uri
+        else:
+            self.card = card
+        self.save()
+
+    def add_bank_account(self, bank_account):
+        """
+        Associates the `BankAccount` represented by `bank_account` with this
+        `Customer`.
+        """
+        if isinstance(bank_account, basestring):
+            self.bank_account_uri = bank_account
+        elif hasattr(bank_account, 'uri'):
+            self.bank_account_uri = bank_account.uri
+        else:
+            self.bank_account = bank_account
+        self.save()
+
+    def debit(self,
+              amount=None,
+              appears_on_statement_as=None,
+              hold_uri=None,
+              meta=None,
+              description=None,
+              source_uri=None,
+              merchant_uri=None,
+              on_behalf_of=None,
+              **kwargs):
+        """
+        :rtype: A `Debit` representing a flow of money from this Customer to
+            your Marketplace's escrow account.
+        :param amount: Amount to debit in cents, must be >= 50
+        :param appears_on_statement_as: description of the payment as it needs
+        to appear on this customer's card statement
+        :param meta: Key/value collection
+        :param description: Human readable description
+        :param source_uri: A specific funding source such as a `Card`
+            associated with this customer. If not specified the `Card` most
+            recently added to this `Customer` is used.
+        :param on_behalf_of: the customer uri of whomever is providing the
+               service or delivering the product.
+        """
+        if not any((amount, hold_uri)):
+            raise ResourceError('Must have an amount or hold uri')
+        if all([hold_uri, source_uri]):
+            raise ResourceError('Must specify only one of hold_uri OR source_uri')
+
+        if on_behalf_of:
+
+            if hasattr(on_behalf_of, 'uri'):
+                on_behalf_of = on_behalf_of.uri
+
+            if not isinstance(on_behalf_of, basestring):
+                raise ValueError(
+                    'The on_behalf_of parameter should to be a customer uri'
+                )
+
+            if on_behalf_of == self.uri:
+                raise ValueError(
+                    'The on_behalf_of parameter MAY NOT be the same customer'
+                    ' as the account you are debiting!'
+                )
+
+        meta = meta or {}
+        return Debit(
+            uri=self.debits_uri,
+            amount=amount,
+            appears_on_statement_as=appears_on_statement_as,
+            hold_uri=hold_uri,
+            meta=meta,
+            description=description,
+            source_uri=source_uri,
+            merchant_uri=merchant_uri,
+            on_behalf_of_uri=on_behalf_of,
+            **kwargs
+        ).save()
+
+    def credit(self,
+               amount,
+               description=None,
+               meta=None,
+               destination_uri=None,
+               appears_on_statement_as=None,
+               debit_uri=None,
+               **kwargs):
+        """
+        Returns a new Credit representing a transfer of funds from your
+        Marketplace's escrow account to this Customer.
+
+        :param amount: Amount to hold in cents
+        :param description: Human readable description
+        :param meta: Key/value collection
+        :param destination_uri: A specific funding destination such as a
+                `BankAccount` associated with this customer.
+        :param appears_on_statement_as: description of the payment as it needs
+        :param debit_uri: the debit corresponding to this particular credit
+
+        Returns:
+            A `Credit` representing the transfer of funds from your
+            Marketplace's escrow account to this Customer.
+        """
+        meta = meta or {}
+        return Credit(
+            uri=self.credits_uri,
+            amount=amount,
+            description=description,
+            meta=meta,
+            destination_uri=destination_uri,
+            appears_on_statement_as=appears_on_statement_as,
+            debit_uri=debit_uri,
+            **kwargs
+        ).save()
+
+    @property
+    def active_card(self):
+        cards = self.cards.filter(is_valid=True, sort='created_at,desc')
+        return cards[0] if cards else None
+
+    @property
+    def active_bank_account(self):
+        bank_accounts = self.bank_accounts.filter(is_valid=True,
+                                                  sort='created_at,desc')
+        return bank_accounts[0] if bank_accounts else None
+
+
 class FilterExpression(object):
     def __init__(self, field, op, value, inv_op):
         self.field = field

tests/suite.py

@@ -538,3 +538,33 @@ def test_28_on_behalf_of(self):
                 exc.exception.args[0],
                 'The on_behalf_of parameter needs to be an account uri'
             )
+
+    def test_29_customers(self):
+        mp = self._create_marketplace()
+        customer = balanced.Customer().save()
+
+        self.assertIsNone(customer.source)
+        card = mp.create_card(**CARD)
+        customer.add_card(card.uri)
+        card = mp.create_card(**CARD)
+        customer.add_card(card)
+        customer.add_card(CARD)
+        self.assertIsNotNone(customer.source)
+        self.assertEqual(customer.source.id, customer.active_card.id)
+
+        self.assertIsNone(customer.destination)
+        bank_account = mp.create_bank_account(**BANK_ACCOUNT)
+        customer.add_bank_account(bank_account.uri)
+        bank_account = mp.create_bank_account(**BANK_ACCOUNT)
+        customer.add_bank_account(bank_account)
+        customer.add_bank_account(BANK_ACCOUNT)
+        self.assertIsNotNone(customer.destination)
+        self.assertEqual(customer.destination.id,
+                         customer.active_bank_account.id)
+
+        debit = customer.debit(100)
+        self.assertEqual(customer.active_card.id, debit.source.id)
+
+        credit = customer.credit(100)
+        self.assertEqual(customer.active_bank_account.id,
+                         credit.destination.id)