Redesign of get_by_query methods for receipts and customers endpoints

.github/workflows/readthedocs.yaml

@@ -5,8 +5,9 @@ name: Document on ReadTheDocs
 on:
   push:
     branches:
-      - readthedocs
       - master
+      - staging
+      - readthedocs
 
 jobs:
   document:

.github/workflows/testpypi.yaml

@@ -4,7 +4,7 @@ name: Build and publish to TestPyPi
 on:
   push:
     branches:
-      - master
+      - staging
 
 jobs:
   build-and-publish:

loyverse/endpoints/customers.py

@@ -1,10 +1,13 @@
 """
 Customers endpoint wrapper class
 
-Actions:
+Possible requests:
 
 * get_by_query: get customers that respect passed in query parameters
-* get_by_id: get customer by passing valid ID
+* get_by_id: get customer with given customer ID
+* get_by_email: get customer with given email
+* get_by_creation_date: get customers created at specific date
+* get_by_creation_dates: get customers created between specific dates
 """
 
 from datetime import datetime, timezone
@@ -18,23 +21,58 @@ def __init__(self, api: Api):
         self._api = api
         self._path = 'customers'
 
-    def get_by_query(self, **kwargs):
+    def get_by_query(self, customer_ids: list = None, email: str = None,
+                     created_at_min: datetime = None, created_at_max: datetime = None,
+                     updated_at_min: datetime = None, updated_at_max: datetime = None,
+                     limit: int = 250, cursor: str = None) -> dict:
         """
-        Retrieves customers that respect the specific query criteria passed in
+        Retrieves customers that respect the specific query criteria passed in. A detailed description of the query
+        parameters is available `here <https://developer.loyverse.com/docs/#tag/Customers/paths/~1customers/get>`_.
 
         Args:
-            **kwargs:  all possible value-pairs that can be used to query the list.
-                A detailed description of the query parameters is available
-                `here <https://developer.loyverse.com/docs/#tag/Customers/paths/~1customers/get>`_.
+            customer_ids (list): filter customers by customer id
+            email (str): filter customer by email
+            created_at_min (datetime): filter customers created after this date (includes timezone info)
+            created_at_max (datetime): filter customers created before this date (includes timezone info)
+            updated_at_min (datetime): filter customers updated after this date (includes timezone info)
+            updated_at_max (datetime): filter customers updated before this date (includes timezone info)
+            limit (int): maximum number of customers to return per request (1 to 250)
+            cursor (str): token to get continuation of return list for requests exceeding limits
         Returns:
             response (dict): formatted customers information (JSON)
         """
 
-        return self._api.request('GET', self._path, params=kwargs)
+        params = dict()
 
-    def get_by_id(self, customer_id: str):
+        if customer_ids is not None:
+            params['customer_ids'] = ','.join(customer_ids)
+
+        if email is not None:
+            params['email'] = email
+
+        if created_at_min is not None:
+            params['created_at_min'] = utc_isoformat(created_at_min)
+
+        if created_at_max is not None:
+            params['created_at_max'] = utc_isoformat(created_at_max)
+
+        if updated_at_min is not None:
+            params['updated_at_min'] = utc_isoformat(updated_at_min)
+
+        if updated_at_max is not None:
+            params['updated_at_max'] = utc_isoformat(updated_at_max)
+
+        if limit is not None:
+            params['limit'] = limit
+
+        if cursor is not None:
+            params['cursor'] = cursor
+
+        return self._api.request('GET', self._path, params=params)
+
+    def get_by_id(self, customer_id: str) -> dict:
         """
-        Retrieves the customer information for a specific customer ID
+        Retrieves the customer information for specific customer ID
 
         Args:
             customer_id (str): string uniquely identifying the customer to be retrieved
@@ -44,7 +82,7 @@ def get_by_id(self, customer_id: str):
 
         return self._api.request('GET', f'{self._path}/{customer_id}')
 
-    def get_by_email(self, email: str):
+    def get_by_email(self, email: str) -> dict:
         """
         Retrieves the customer information for a user with the specific email
 
@@ -56,7 +94,7 @@ def get_by_email(self, email: str):
 
         return self.get_by_query(email=email)
 
-    def get_by_creation_date(self, date: datetime):
+    def get_by_creation_date(self, date: datetime) -> dict:
         """
         Retrieve customers information for a specific creation date
 
@@ -66,14 +104,12 @@ def get_by_creation_date(self, date: datetime):
             response (dict): formatted customers information (JSON)
         """
 
-        timestamp_start = utc_isoformat(day_start(date))
-        timestamp_end = utc_isoformat(day_end(date))
-        data = self.get_by_query(created_at_min=timestamp_start,
-                                 created_at_max=timestamp_end,
+        data = self.get_by_query(created_at_min=day_start(date),
+                                 created_at_max=day_end(date),
                                  )
         return data
 
-    def get_by_creation_dates(self, start_date: datetime, end_date: datetime = None):
+    def get_by_creation_dates(self, start_date: datetime, end_date: datetime = None) -> dict:
         """
         Retrieve customers information for a creation date range
 
@@ -87,9 +123,9 @@ def get_by_creation_dates(self, start_date: datetime, end_date: datetime = None)
         if end_date is None:
             end_date = datetime.now(timezone.utc)
 
-        timestamp_start = utc_isoformat(start_date)
-        timestamp_end = utc_isoformat(end_date)
-        data = self.get_by_query(created_at_min=timestamp_start,
-                                 created_at_max=timestamp_end,
+        data = self.get_by_query(created_at_min=day_start(start_date),
+                                 created_at_max=day_end(end_date),
                                  )
         return data
+
+    # TODO: Implement parsing to dataframes

loyverse/endpoints/receipts.py

@@ -1,12 +1,12 @@
 """
 Receipts endpoint wrapper class
 
-Actions:
+Possible requests:
 
 * get_by_query: get receipts that respect passed in query parameters
-* get_by_id: get receipt passing valid ID
+* get_by_id: get receipt with a given ID
 * get_by_date: get receipts for a given date
-* get_by_dates: get receipts between two dates (if end-date is left empty, then it returns receipts until present day)
+* get_by_dates: get receipts between two dates
 """
 
 import pandas as pd
@@ -22,23 +22,75 @@ def __init__(self, api: Api):
         self._api = api
         self._path = 'receipts'
 
-    def get_by_query(self, **kwargs):
+    def get_by_query(self, receipt_numbers: list = None, since_receipt_number: str = None,
+                     before_receipt_number: str = None, store_id: str = None, order: str = None, source: str = None,
+                     updated_at_min: datetime = None, updated_at_max: datetime = None,
+                     created_at_min: datetime = None, created_at_max: datetime = None, limit: int = 250,
+                     cursor: str = None) -> dict:
         """
-        Retrieves receipts that respect the specific query criteria passed in
+        Retrieves receipts that respect the specific query criteria passed in. A detailed description of the query 
+        parameters is available `here <https://developer.loyverse.com/docs/#tag/Receipts/paths/~1receipts/get>`_.
 
         Args:
-            **kwargs:  all possible value-pairs that can be used to query the list.
-                A detailed description of the query parameters is available
-                `here <https://developer.loyverse.com/docs/#tag/Receipts/paths/~1receipts/get>`_.
+            receipt_numbers (list): filter receipts by receipt numbers
+            since_receipt_number (str): return only receipts after this receipt number
+            before_receipt_number (str): return only receipts before this receipt number
+            store_id (str): filter receipts by store id
+            order (str): filter receipts by order
+            source (str): filter receipts by source (e.g. My app)
+            updated_at_min (datetime): filter receipts updated after this date (includes timezone info)
+            updated_at_max (datetime): filter receipts updated before this date (includes timezone info)
+            created_at_min (datetime): filter receipts created after this date (includes timezone info)
+            created_at_max (datetime): filter receipts created before this date (includes timezone info)
+            limit (int): maximum number of receipts to return per request (1 to 250)
+            cursor (str): token to get continuation of return list for requests exceeding limits
         Returns:
             response (dict): formatted receipts information (JSON)
         """
 
-        response = self._api.request('GET', self._path, params=kwargs)
+        params = dict()
+
+        if receipt_numbers is not None:
+            params['receipt_numbers'] = ','.join(receipt_numbers)
+
+        if since_receipt_number is not None:
+            params['since_receipt_number'] = since_receipt_number
+
+        if before_receipt_number is not None:
+            params['before_receipt_number'] = before_receipt_number
+
+        if store_id is not None:
+            params['store_id'] = store_id
+
+        if order is not None:
+            params['order'] = order
+
+        if source is not None:
+            params['source'] = source
+
+        if updated_at_min is not None:
+            params['updated_at_min'] = utc_isoformat(updated_at_min)
+
+        if updated_at_max is not None:
+            params['updated_at_max'] = utc_isoformat(updated_at_max)
+
+        if created_at_min is not None:
+            params['created_at_min'] = utc_isoformat(created_at_min)
+
+        if created_at_max is not None:
+            params['created_at_max'] = utc_isoformat(created_at_max)
+
+        if limit is not None:
+            params['limit'] = limit
+
+        if cursor is not None:
+            params['cursor'] = cursor
+
+        response = self._api.request('GET', self._path, params=params)
 
         return response
 
-    def get_by_id(self, receipt_id: str):
+    def get_by_id(self, receipt_id: str) -> dict:
         """
         Retrieves the receipts information for a specific receipt ID
 
@@ -50,7 +102,7 @@ def get_by_id(self, receipt_id: str):
 
         return self._api.request('GET', f'{self._path}/{receipt_id}')
 
-    def get_by_date(self, date: datetime):
+    def get_by_date(self, date: datetime) -> dict:
         """
         Retrieve receipts information for a specific day
 
@@ -60,14 +112,12 @@ def get_by_date(self, date: datetime):
             response (dict): formatted receipts information (JSON)
         """
 
-        timestamp_start = utc_isoformat(day_start(date))
-        timestamp_end = utc_isoformat(day_end(date))
-        data = self.get_by_query(created_at_min=timestamp_start,
-                                 created_at_max=timestamp_end,
+        data = self.get_by_query(created_at_min=day_start(date),
+                                 created_at_max=day_end(date),
                                  )
         return data
 
-    def get_by_dates(self, start_date: datetime, end_date: datetime = None):
+    def get_by_dates(self, start_date: datetime, end_date: datetime = None) -> dict:
         """
         Retrieves receipts information for a specific date interval.
 
@@ -81,11 +131,8 @@ def get_by_dates(self, start_date: datetime, end_date: datetime = None):
         if end_date is None:
             end_date = datetime.now(timezone.utc)
 
-        timestamp_start = utc_isoformat(day_start(start_date))
-        timestamp_end = utc_isoformat(end_date)
-
-        data = self.get_by_query(created_at_min=timestamp_start,
-                                 created_at_max=timestamp_end
+        data = self.get_by_query(created_at_min=day_start(start_date),
+                                 created_at_max=day_end(end_date),
                                  )
         return data
 

tests/test_receipts.py

@@ -67,7 +67,7 @@ def test_get_receipts_by_dates():
     end_date = add_timezone(datetime(2020, 10, 1), timezone)
 
     # Expected results
-    receipts_length = 1143
+    receipts_length = 1189
 
     client = Client()
     receipts = client.receipts.get_by_dates(start_date, end_date)