Voucher improvements (#43)

- Expanded voucher attributes and operations

Author: joamag

src/budy/controllers/api/voucher.py

@@ -51,10 +51,10 @@ def create(self):
         voucher = voucher.map()
         return voucher
 
-    @appier.route("/api/vouchers/<int:id>", "GET", json=True)
+    @appier.route("/api/vouchers/<str:key>", "GET", json=True)
     @appier.ensure(token="admin")
-    def show(self, id):
-        voucher = budy.Voucher.get_e(id=id, map=True)
+    def show(self, key):
+        voucher = budy.Voucher.get_e(key=key, map=True)
         return voucher
 
     @appier.route("/api/vouchers/value", "POST", json=True)
@@ -64,12 +64,22 @@ def create_value(self):
         key = object.get("key", None)
         amount = object.get("amount", None)
         currency = object.get("currency", None)
-        unlimited = object.get("unlimited", None)
-        key = self.field("key", key)
+        usage_limit = object.get("usage_limit", 0)
+        unlimited = object.get("unlimited", False)
+        start = object.get("start", None)
+        expiration = object.get("expiration", None)
+        meta = object.get("meta", {})
+        key = self.field("key", key, cast=str)
         amount = self.field("amount", amount, cast=float)
         currency = self.field("currency", currency, cast=str)
+        usage_limit = self.field("usage_limit", usage_limit, cast=int)
         unlimited = self.field("unlimited", unlimited, cast=bool)
-        voucher = budy.Voucher.create_value_s(key, amount, currency, unlimited)
+        start = self.field("start", start, cast=int)
+        expiration = self.field("expiration", expiration, cast=int)
+        meta = self.field("meta", meta, cast=dict)
+        voucher = budy.Voucher.create_value_s(
+            key, amount, currency, usage_limit, unlimited, start, expiration, meta
+        )
         voucher = voucher.map()
         return voucher
 
@@ -79,8 +89,45 @@ def create_percentage(self):
         object = appier.get_object()
         key = object.get("key", None)
         percentage = object.get("percentage", None)
-        key = self.field("key", key)
+        usage_limit = object.get("usage_limit", 0)
+        start = object.get("start", None)
+        expiration = object.get("expiration", None)
+        meta = object.get("meta", {})
+        unlimited = object.get("unlimited", None)
+        key = self.field("key", key, cast=str)
         percentage = self.field("percentage", percentage, cast=float)
-        voucher = budy.Voucher.create_percentage_s(key, percentage)
+        usage_limit = self.field("usage_limit", usage_limit, cast=int)
+        start = self.field("start", start, cast=int)
+        expiration = self.field("expiration", expiration, cast=int)
+        meta = self.field("meta", meta, cast=dict)
+        unlimited = self.field("unlimited", unlimited, cast=bool)
+        voucher = budy.Voucher.create_percentage_s(
+            key, percentage, usage_limit, start, expiration, meta
+        )
+        voucher = voucher.map()
+        return voucher
+
+    @appier.route("/api/vouchers/<str:key>/use", "POST", json=True)
+    @appier.ensure(token="admin")
+    def use(self, key):
+        object = appier.get_object()
+        amount = object.get("amount", None)
+        currency = object.get("currency", None)
+        justification = object.get("justification", None)
+        save_use = object.get("save_use", True)
+        voucher = budy.Voucher.get_e(key=key)
+        voucher_use = voucher.use_s(
+            amount, currency=currency, justification=justification, save_use=save_use
+        )
+        voucher = voucher.map()
+        if voucher_use:
+            voucher["use"] = voucher_use.map()
+        return voucher
+
+    @appier.route("/api/vouchers/<str:key>/disuse", "POST", json=True)
+    @appier.ensure(token="admin")
+    def disuse(self, key):
+        voucher = budy.Voucher.get_e(key=key)
+        voucher.disuse_s()
         voucher = voucher.map()
         return voucher

src/budy/models/__init__.py

@@ -84,5 +84,6 @@
 from .store import Store
 from .subscription import Subscription
 from .voucher import Voucher
+from .voucher_use import VoucherUse
 from .wishlist_line import WishlistLine
 from .wishlist import Wishlist

src/budy/models/voucher.py

@@ -35,21 +35,41 @@
 import appier_extras
 
 from . import base
+from . import voucher_use
 
 
 class Voucher(base.BudyBase):
-    key = appier.field(index=True, safe=True, immutable=True)
+    key = appier.field(
+        index=True,
+        safe=True,
+        immutable=True,
+        observations="""The (secret) key of the voucher, considered to be
+        the unique identifier of the voucher, this is the key that will
+        be used to identify the voucher when it is used""",
+    )
 
     amount = appier.field(
         type=commons.Decimal,
         index=True,
         initial=commons.Decimal(0.0),
         safe=True,
         immutable=True,
+        observations="""The amount of the voucher, meaning the total
+        amount of the voucher that can be used, this is the amount
+        that will be deducted from the order total when the voucher
+        is used, if this value is set to zero the voucher is considered
+        to be a percentage based voucher""",
     )
 
     used_amount = appier.field(
-        type=commons.Decimal, initial=commons.Decimal(0.0), index=True, safe=True
+        type=commons.Decimal,
+        initial=commons.Decimal(0.0),
+        index=True,
+        safe=True,
+        observations="""The amount of the voucher that has been used,
+        meaning that the remaining amount of the voucher that can be
+        used can be calculated by subtracting the used amount from the
+        amount""",
     )
 
     percentage = appier.field(
@@ -58,6 +78,8 @@ class Voucher(base.BudyBase):
         index=True,
         safe=True,
         immutable=True,
+        observations="""The percentage of discount to be applied when
+        using the voucher, meaning the voucher is percentage based""",
     )
 
     currency = appier.field(
@@ -175,12 +197,27 @@ def is_snapshot(cls):
             ("Key", "key", str),
             ("Amount", "amount", commons.Decimal),
             ("Currency", "currency", str),
+            ("Usage Limit", "usage_limit", int, 0),
             ("Unlimited", "unlimited", bool, False),
+            ("Start", "start", int, None),
+            ("Expiration", "expiration", int, None),
+            ("Metadata", "meta", dict, {}),
         ),
         factory=True,
     )
-    def create_value_s(cls, key, amount, currency, unlimited):
-        voucher = cls(key=key, amount=amount, currency=currency, unlimited=unlimited)
+    def create_value_s(
+        cls, key, amount, currency, usage_limit, unlimited, start, expiration, meta
+    ):
+        voucher = cls(
+            key=key,
+            amount=amount,
+            currency=currency,
+            usage_limit=usage_limit,
+            unlimited=unlimited,
+            start=start,
+            expiration=expiration,
+            meta=meta,
+        )
         voucher.save()
         return voucher
 
@@ -191,29 +228,62 @@ def create_value_s(cls, key, amount, currency, unlimited):
             ("Key", "key", str),
             ("Amount", "amount", commons.Decimal),
             ("Currency", "currency", str),
+            ("Usage Limit", "usage_limit", int, 0),
             ("Unlimited", "unlimited", bool, False),
+            ("Start", "start", int, None),
+            ("Expiration", "expiration", int, None),
+            ("Metadata", "meta", dict, {}),
             ("Count", "count", int, 1),
         ),
     )
-    def create_value_multiple_s(cls, key, amount, currency, unlimited, count):
+    def create_value_multiple_s(
+        cls,
+        key,
+        amount,
+        currency,
+        usage_limit,
+        unlimited,
+        start,
+        expiration,
+        meta,
+        count,
+    ):
         key = key or cls.secret_g()
         for index in appier.legacy.xrange(count):
             voucher = cls(
                 key=key + "-" + str(index),
                 amount=amount,
                 currency=currency,
+                usage_limit=usage_limit,
                 unlimited=unlimited,
+                start=start,
+                expiration=expiration,
+                meta=meta,
             )
             voucher.save()
 
     @classmethod
     @appier.operation(
         name="Create Percentage",
-        parameters=(("Key", "key", str), ("Percentage", "percentage", commons.Decimal)),
+        parameters=(
+            ("Key", "key", str),
+            ("Percentage", "percentage", commons.Decimal),
+            ("Usage Limit", "usage_limit", int, 0),
+            ("Start", "start", int, None),
+            ("Expiration", "expiration", int, None),
+            ("Metadata", "meta", dict, {}),
+        ),
         factory=True,
     )
-    def create_percentage_s(cls, key, percentage):
-        voucher = cls(key=key, percentage=percentage)
+    def create_percentage_s(cls, key, percentage, usage_limit, start, expiration, meta):
+        voucher = cls(
+            key=key,
+            percentage=percentage,
+            usage_limit=usage_limit,
+            start=start,
+            expiration=expiration,
+            meta=meta,
+        )
         voucher.save()
         return voucher
 
@@ -223,13 +293,26 @@ def create_percentage_s(cls, key, percentage):
         parameters=(
             ("Key", "key", str),
             ("Percentage", "percentage", commons.Decimal),
+            ("Usage Limit", "usage_limit", int, 0),
+            ("Start", "start", int, None),
+            ("Expiration", "expiration", int, None),
+            ("Metadata", "meta", dict, {}),
             ("Count", "count", int, 1),
         ),
     )
-    def create_percentage_multiple_s(cls, key, percentage, count):
+    def create_percentage_multiple_s(
+        cls, key, percentage, usage_limit, start, expiration, meta, count
+    ):
         key = key or cls.secret_g()
         for index in appier.legacy.xrange(count):
-            voucher = cls(key=key + "-" + str(index), percentage=percentage)
+            voucher = cls(
+                key=key + "-" + str(index),
+                percentage=percentage,
+                usage_limit=usage_limit,
+                start=start,
+                expiration=expiration,
+                meta=meta,
+            )
             voucher.save()
 
     def pre_create(self):
@@ -245,13 +328,24 @@ def pre_update(self):
         if self.used and not self.is_used():
             self.used = False
 
-    def use_s(self, amount, currency=None):
+    def use_s(self, amount, currency=None, justification=None, save_use=True):
         amount_l = self.to_local(amount, currency)
         appier.verify(self.is_valid(amount=amount, currency=currency))
         if self.is_value and not self.unlimited:
             self.used_amount += commons.Decimal(amount_l)
         self.usage_count += 1
         self.save()
+        if save_use:
+            usage_type = "value" if self.is_value else "percentage"
+            voucher_use_ = voucher_use.VoucherUse(
+                usage_type=usage_type,
+                amount=amount,
+                currency=currency,
+                justification=justification,
+                voucher=self,
+            )
+            voucher_use_.save()
+            return voucher_use_
 
     def disuse_s(self, amount, currency=None):
         appier.verify(self.usage_count > 0)