Add functionality to send receipt templates

Author: Pashutan Modaresi

docs/autogen.py

@@ -19,16 +19,22 @@
 
 PAGES = [
     {
-        "page": "list_template/list_template.md",
+        "page": "receipt_template/receipt_template.md",
         "classes": [
-            fbotics.models.payloads.list_template.ListTemplatePayload,
+            fbotics.models.payloads.receipt_template.ReceiptTemplatePayload,
+            fbotics.models.payloads.receipt_template.Element,
+            fbotics.models.payloads.receipt_template.Address,
+            fbotics.models.payloads.receipt_template.Summary,
+            fbotics.models.payloads.receipt_template.Adjustment,
         ],
     },
+    {
+        "page": "list_template/list_template.md",
+        "classes": [fbotics.models.payloads.list_template.ListTemplatePayload],
+    },
     {
         "page": "generic_template/generic_template.md",
-        "classes": [
-            fbotics.models.payloads.generic_template.GenericTemplatePayload,
-        ],
+        "classes": [fbotics.models.payloads.generic_template.GenericTemplatePayload],
     },
     {
         "page": "client/client.md",

docs/mkdocs.yml

@@ -25,3 +25,6 @@ nav:
 - List Template:
   - Template Payload: list_template/list_template.md
   - Example: list_template/example.md
+- Receipt Template:
+  - Template Payload: receipt_template/receipt_template.md
+  - Example: receipt_template/example.md

docs/templates/receipt_template/example.md

@@ -0,0 +1,93 @@
+This is an example to send Receipt Templates using FBotics:
+
+```python
+from fbotics.client import Client
+from fbotics.models.quick_reply import QuickReply
+from fbotics.models.payloads.receipt_template import (
+    Element,
+    Adjustment,
+    Summary,
+    Address,
+)
+
+
+client = Client(page_access_token=PAGE_ACCESS_TOKEN)
+
+e1 = Element(
+    dict(
+        title="Classic White T-Shirt",
+        subtitle="100% Soft and Luxurious Cotton",
+        quantity=2,
+        price=50,
+        currency="USD",
+        image_url="http://petersapparel.parseapp.com/img/whiteshirt.png",
+    )
+)
+
+e2 = Element(
+    dict(
+        title="Classic Gray T-Shirt",
+        subtitle="100% Soft and Luxurious Cotton",
+        quantity=1,
+        price=25,
+        currency="USD",
+        image_url="http://petersapparel.parseapp.com/img/grayshirt.png",
+    )
+)
+
+address = Address(
+    dict(
+        street_1="1 Hacker Way",
+        street_2="",
+        city="Menlo Park",
+        postal_code="94025",
+        state="CA",
+        country="US",
+    )
+)
+
+summary = Summary(
+    dict(subtotal=75.00, shipping_cost=4.95, total_tax=6.19, total_cost=56.14)
+)
+
+adjustments = [
+    Adjustment(dict(name="New Customer Discount", amount=20)),
+    Adjustment(dict(name="$10 Off Coupon", amount=10)),
+]
+
+qr1 = QuickReply(
+    dict(
+        content_type="text",
+        title="Yes",
+        payload="payload1",
+        image_url="http://i64.tinypic.com/1hothh.png",
+    )
+)
+
+qr2 = QuickReply(
+    dict(
+        content_type="text",
+        title="No",
+        payload="payload2",
+        image_url="http://i63.tinypic.com/2pqpbth.png",
+    )
+)
+
+response = client.send_receipt_template(
+    recipient_id=RECIPIENT_ID,
+    quick_replies=[qr1, qr2],
+    elements=[e1, e2],
+    recipient_name="Stephane Crozatier",
+    order_number="12345678902",
+    currency="USD",
+    payment_method="Visa 2345",
+    timestamp="1428444852",
+    address=address,
+    summary=summary,
+    adjustments=adjustments,
+)
+```
+
+<p float="center">
+    <img src="https://scontent-frx5-1.xx.fbcdn.net/v/t39.2365-6/23208289_889588377870772_7170760265053503488_n.png?_nc_cat=103&_nc_ht=scontent-frx5-1.xx&oh=7c03f776fea86f91a52c799d6eb02825&oe=5D42A68C" width="40%" />
+</p>

docs/templates/receipt_template/receipt_template.md

@@ -0,0 +1,4 @@
+The receipt template allows you to send an order confirmation as a structured message. The template may include an order summary, payment details, and shipping information.
+
+
+{{autogenerated}}

fbotics/_version.py

@@ -120,7 +120,7 @@ def versions_from_parentdir(parentdir_prefix, root, verbose):
         dirname = os.path.basename(root)
         if dirname.startswith(parentdir_prefix):
             return {
-                "version": dirname[len(parentdir_prefix):],
+                "version": dirname[len(parentdir_prefix) :],
                 "full-revisionid": None,
                 "dirty": False,
                 "error": None,
@@ -132,8 +132,8 @@ def versions_from_parentdir(parentdir_prefix, root, verbose):
 
     if verbose:
         print(
-                "Tried directories %s but none started with prefix %s"
-                % (str(rootdirs), parentdir_prefix)
+            "Tried directories %s but none started with prefix %s"
+            % (str(rootdirs), parentdir_prefix)
         )
     raise NotThisMethod("rootdir doesn't start with parentdir_prefix")
 
@@ -190,7 +190,7 @@ def git_versions_from_keywords(keywords, tag_prefix, verbose):
     # starting in git-1.8.3, tags are listed as "tag: foo-1.0" instead of
     # just "foo-1.0". If we see a "tag: " prefix, prefer those.
     TAG = "tag: "
-    tags = set([r[len(TAG):] for r in refs if r.startswith(TAG)])
+    tags = set([r[len(TAG) :] for r in refs if r.startswith(TAG)])
     if not tags:
         # Either we're using git < 1.8.3, or there really are no tags. We use
         # a heuristic: assume all version tags have a digit. The old git %d
@@ -207,7 +207,7 @@ def git_versions_from_keywords(keywords, tag_prefix, verbose):
     for ref in sorted(tags):
         # sorting will prefer e.g. "2.0" over "2.0rc1"
         if ref.startswith(tag_prefix):
-            r = ref[len(tag_prefix):]
+            r = ref[len(tag_prefix) :]
             if verbose:
                 print("picking %s" % r)
             return {
@@ -307,7 +307,7 @@ def git_pieces_from_vcs(tag_prefix, root, verbose, run_command=run_command):
                 tag_prefix,
             )
             return pieces
-        pieces["closest-tag"] = full_tag[len(tag_prefix):]
+        pieces["closest-tag"] = full_tag[len(tag_prefix) :]
 
         # distance: number of commits since tag
         pieces["distance"] = int(mo.group(2))

fbotics/client/__init__.py

@@ -7,6 +7,7 @@
 from fbotics.models.payloads.button_template import ButtonTemplatePayload
 from fbotics.models.payloads.generic_template import GenericTemplatePayload
 from fbotics.models.payloads.list_template import ListTemplatePayload
+from fbotics.models.payloads.receipt_template import ReceiptTemplatePayload
 from fbotics.models.payloads.rich_media import RichMediaPayload
 from fbotics.models.recipient import Recipient
 
@@ -18,13 +19,13 @@ def __init__(self, page_access_token=None):
         self.page_access_token = page_access_token
 
     def send_button_template(
-            self,
-            recipient_id=None,
-            user_ref=None,
-            phone_number=None,
-            text=None,
-            quick_replies=None,
-            buttons=None,
+        self,
+        recipient_id=None,
+        user_ref=None,
+        phone_number=None,
+        text=None,
+        quick_replies=None,
+        buttons=None,
     ):
         """Sends a button template to the recipient.
 
@@ -47,12 +48,12 @@ def send_button_template(
         return response
 
     def send_generic_template(
-            self,
-            recipient_id=None,
-            user_ref=None,
-            phone_number=None,
-            elements=None,
-            quick_replies=None,
+        self,
+        recipient_id=None,
+        user_ref=None,
+        phone_number=None,
+        elements=None,
+        quick_replies=None,
     ):
         """Sends a generic template to the recipient.
 
@@ -75,13 +76,13 @@ def send_generic_template(
         return response
 
     def send_list_template(
-            self,
-            recipient_id=None,
-            user_ref=None,
-            phone_number=None,
-            elements=None,
-            buttons=None,
-            quick_replies=None
+        self,
+        recipient_id=None,
+        user_ref=None,
+        phone_number=None,
+        elements=None,
+        buttons=None,
+        quick_replies=None,
     ):
         """Sends a list template to the recipient.
 
@@ -104,13 +105,67 @@ def send_list_template(
         response = self._post(message, recipient_id, user_ref, phone_number)
         return response
 
+    def send_receipt_template(
+        self,
+        recipient_id=None,
+        user_ref=None,
+        phone_number=None,
+        recipient_name=None,
+        elements=None,
+        order_number=None,
+        currency=None,
+        payment_method=None,
+        timestamp=None,
+        address=None,
+        summary=None,
+        adjustments=None,
+        quick_replies=None,
+    ):
+        """Sends a receipt template to the recipient.
+
+        # Arguments
+            recipient_id: page specific id of the recipient
+            user_ref: optional. user_ref from the checkbox plugin
+            phone_number: Optional. Phone number of the recipient with the format +1(212)555-2368. Your bot must be approved for Customer Matching to send messages this way.
+            elements: Optional. Array of a maximum of 100 element objects that describe items in the order. Sort order of the elements is not guaranteed.
+            order_number: The order number. Must be unique.
+            currency: The currency of the payment.
+            payment_method: The payment method used. Providing enough information for the customer to decipher which payment method and account they used is recommended. This can be a custom string, such as, "Visa 1234".
+            timestamp: Optional. Timestamp of the order in seconds.
+            address: Optional. The shipping address of the order.
+            summary: The payment summary.
+            adjustments: Optional. An array of payment objects that describe payment adjustments, such as discounts.
+            quick_replies: An array of objects the describe the quick reply buttons to send. A maximum of 11 quick replies are supported.
+
+        """
+
+        receipt_template_payload = ReceiptTemplatePayload(
+            dict(
+                template_type="receipt",
+                recipient_name=recipient_name,
+                elements=elements,
+                order_number=order_number,
+                currency=currency,
+                payment_method=payment_method,
+                timestamp=timestamp,
+                address=address,
+                summary=summary,
+                adjustments=adjustments,
+            )
+        )
+        attachment = Attachment(dict(type="template", payload=receipt_template_payload))
+        message = Message({"quick_replies": quick_replies, "attachment": attachment})
+
+        response = self._post(message, recipient_id, user_ref, phone_number)
+        return response
+
     def send_quick_replies(
-            self,
-            recipient_id=None,
-            user_ref=None,
-            phone_number=None,
-            text=None,
-            quick_replies=None,
+        self,
+        recipient_id=None,
+        user_ref=None,
+        phone_number=None,
+        text=None,
+        quick_replies=None,
     ):
         """Sends quick replies to the recipient.
 
@@ -147,12 +202,12 @@ def send_text(self, recipient_id=None, user_ref=None, phone_number=None, text=No
         return response
 
     def send_image(
-            self,
-            recipient_id=None,
-            user_ref=None,
-            phone_number=None,
-            url=None,
-            quick_replies=None,
+        self,
+        recipient_id=None,
+        user_ref=None,
+        phone_number=None,
+        url=None,
+        quick_replies=None,
     ):
         """Sends an image to the recipient.
 
@@ -171,12 +226,12 @@ def send_image(
         return response
 
     def send_audio(
-            self,
-            recipient_id=None,
-            user_ref=None,
-            phone_number=None,
-            url=None,
-            quick_replies=None,
+        self,
+        recipient_id=None,
+        user_ref=None,
+        phone_number=None,
+        url=None,
+        quick_replies=None,
     ):
         """Sends an audio to the recipient.
 
@@ -195,12 +250,12 @@ def send_audio(
         return response
 
     def send_file(
-            self,
-            recipient_id=None,
-            user_ref=None,
-            phone_number=None,
-            url=None,
-            quick_replies=None,
+        self,
+        recipient_id=None,
+        user_ref=None,
+        phone_number=None,
+        url=None,
+        quick_replies=None,
     ):
         """Sends a file to the recipient.
 
@@ -241,8 +296,8 @@ def _post(self, message, recipient_id=None, user_ref=None, phone_number=None):
         response = requests.post(API_URL, params=params, json=request.to_primitive())
         json_response = response.json()
         if (
-                response.status_code == 400
-                and json_response.get("error", {}).get("type", "") == "OAuthException"
+            response.status_code == 400
+            and json_response.get("error", {}).get("type", "") == "OAuthException"
         ):
             raise OAuthException(json_response.get("error").get("message", ""))
         return response