supersaas-api-client 2.1.0__py3-none-any.whl

SuperSaaS/API/Appointments.py

@@ -0,0 +1,221 @@
+from .BaseApi import BaseApi
+from ..Models.Appointment import Appointment
+from ..Models.Slot import Slot
+
+
+class Appointments(BaseApi):
+    def agenda(self, schedule_id, user, from_time=None, slot=False):
+        path = f"/agenda/{self._validate_id(schedule_id)}"
+        query = {
+            'user': self._validate_present(user),
+            'from': self._validate_datetime(from_time) if from_time else None
+        }
+        if slot:
+            query['slot'] = True
+        res = self.client.get(path, query)
+        return self.__map_slots_or_bookings(res)
+
+    def agenda_slots(self, schedule_id, user_id, from_time=None):
+        """Deprecated, will be removed in a future version. Use `agenda(..., slot=True)` instead."""
+        path = f"/agenda/{self._validate_id(schedule_id)}"
+        query = {
+            'user': self._validate_present(user_id),
+            'from': self._validate_datetime(from_time) if from_time else None,
+            'slot': 'true'
+        }
+        res = self.client.get(path, query)
+        return self.__map_slots_or_bookings(res)
+
+    def available(self,
+                  schedule_id,
+                  from_time=None,
+                  length_minutes=None,
+                  resource=None,
+                  full=None,
+                  limit=None):
+        path = f"/free/{self._validate_id(schedule_id)}"
+        query = {
+            'length':
+            self._validate_number(length_minutes) if length_minutes else None,
+            'from': self._validate_datetime(from_time) if from_time else None,
+            'resource': resource,
+            'full': 'true' if full else None,
+            'maxresults': self._validate_number(limit) if limit else None
+        }
+        res = self.client.get(path, query)
+        return self.__map_slots_or_bookings(res)
+
+    def list(self, schedule_id, form=None, start_time=None, limit=None, finish=None):
+        path = "/bookings"
+        query = {
+            'schedule_id': self._validate_id(schedule_id),
+            'form': 'true' if form else None,
+            'start':
+            self._validate_datetime(start_time) if start_time else None,
+            'limit': self._validate_number(limit) if limit else None,
+            'finish':
+                self._validate_datetime(finish) if finish else None
+        }
+        res = self.client.get(path, query)
+        return self.__map_slots_or_bookings(res)
+
+    def get(self, schedule_id, appointment_id=None):
+        query = {'schedule_id': self._validate_id(schedule_id)}
+        path = f"/bookings/{self._validate_id(appointment_id)}"
+        res = self.client.get(path, query)
+        return Appointment(res)
+
+    def create(self, schedule_id, user_id, attributes,
+               form=None,
+               webhook=None):
+        path = "/bookings"
+        params = self.__create_update_params(schedule_id, attributes, form, webhook)
+        if user_id:
+            params['user_id'] = self._validate_id(user_id)
+        params['booking'] = dict(
+            filter(lambda item: item[1] is not None,
+                   params['booking'].items()))
+        res = self.client.post(path, params)
+        return {'location': res}
+
+    def update(self, schedule_id, appointment_id, attributes, form=None, webhook=None):
+        """
+        Update an existing appointment/booking
+        """
+        path = f"/bookings/{self._validate_id(appointment_id)}"
+        params = self.__create_update_params(schedule_id, attributes, form, webhook)
+
+        # Attributes passed as {'booking': None} are sent as an empty booking
+        if params.get('booking') is None:
+            params['booking'] = {}
+
+        # Filter out None values from booking attributes
+        params['booking'] = {k: v for k, v in params['booking'].items() if v is not None}
+
+        res = self.client.put(path, params)
+        return Appointment(res)
+
+    def delete(self, schedule_id, appointment_id, webhook=None):
+        path = f'/bookings/{self._validate_id(appointment_id)}'
+        query = {'schedule_id': schedule_id, 'webhook': 'true' if webhook else None}
+        return self.client.delete(path, None, query)
+
+    def changes(self,
+                schedule_id,
+                from_time=None,
+                to=None,
+                slot=False,
+                user=None,
+                limit=None,
+                offset=None):
+        path = f"/changes/{self._validate_id(schedule_id)}"
+        params = self.__build_param({}, from_time, to, slot, user, limit,
+                                    offset)
+        res = self.client.get(path, params)
+        return self.__map_slots_or_bookings(res)
+
+    def changes_slots(self, schedule_id, from_time=None):
+        """Deprecated, will be removed in a future version. Use `changes(..., slot=True)` instead."""
+        path = f"/changes/{self._validate_id(schedule_id)}"
+        query = {
+            'from': self._validate_datetime(from_time) if from_time else None,
+            'slot': 'true'
+        }
+        res = self.client.get(path, query)
+        return self.__map_slots_or_bookings(res)
+
+    def range(self,
+              schedule_id,
+              today=False,
+              from_time=None,
+              to=None,
+              slot=False,
+              user=None,
+              resource_id=None,
+              service_id=None,
+              limit=None,
+              offset=None):
+        path = f"/range/{self._validate_id(schedule_id)}"
+        params = {}
+        params = self.__build_param(params, from_time, to, slot, user, limit,
+                                    offset, resource_id, service_id)
+        if today:
+            params['today'] = True
+        res = self.client.get(path, params)
+        return self.__map_slots_or_bookings(res)
+
+    def __create_update_params(self, schedule_id, attributes,
+                               form=None,
+                               webhook=None):
+        # Attributes may be passed already wrapped as {'booking': {...}}
+        if isinstance(attributes, dict) and 'booking' in attributes:
+            attributes = attributes['booking'] or {}
+        params = {
+            'schedule_id': self._validate_id(schedule_id),
+            'booking': {
+                'start': attributes.get('start', None),
+                'finish': attributes.get('finish', None),
+                'email': attributes.get('email', None),
+                'full_name': attributes.get('full_name', None),
+                'address': attributes.get('address', None),
+                'mobile': attributes.get('mobile', None),
+                'phone': attributes.get('phone', None),
+                'country': attributes.get('country', None),
+                'field_1': attributes.get('field_1', None),
+                'field_2': attributes.get('field_2', None),
+                'field_1_r': attributes.get('field_1_r', None),
+                'field_2_r': attributes.get('field_2_r', None),
+                'super_field': attributes.get('super_field', None),
+                'resource_id': attributes.get('resource_id', None),
+                'slot_id': attributes.get('slot_id', None),
+                # description is for resource schedules, quantity (number of places) for capacity schedules,
+                # form_id attaches an existing form
+                'description': attributes.get('description', None),
+                'quantity': attributes.get('quantity', None),
+                'form_id': attributes.get('form_id', None),
+            }
+        }
+        if form:
+            params['form'] = form
+        if webhook:
+            params['webhook'] = webhook
+        return params
+
+    def __map_slots_or_bookings(self, obj):
+        if isinstance(obj, list):
+            return [Appointment(attributes) for attributes in obj]
+        if 'slots' in obj:
+            return [Slot(attributes) for attributes in obj.get('slots', [])]
+        return [
+            Appointment(attributes)
+            for attributes in obj.get('bookings', [])
+        ]
+
+    def __build_param(self,
+                      params,
+                      from_time,
+                      to,
+                      slot,
+                      user,
+                      limit,
+                      offset,
+                      resource_id=None,
+                      service_id=None):
+        if from_time:
+            params['from'] = self._validate_datetime(from_time)
+        if to:
+            params['to'] = self._validate_datetime(to)
+        if slot:
+            params['slot'] = True
+        if user or user == 0:
+            params['user'] = self._validate_user(user)
+        if limit:
+            params['limit'] = self._validate_number(limit)
+        if offset:
+            params['offset'] = self._validate_number(offset)
+        if resource_id is not None:
+            params['resource_id'] = self._validate_id(resource_id)
+        if service_id is not None:
+            params['service_id'] = self._validate_id(service_id)
+
+        return params

SuperSaaS/API/BaseApi.py

@@ -0,0 +1,69 @@
+import re
+from datetime import datetime
+from SuperSaaS.Error import Error
+
+
+class BaseApi:
+    INTEGER_REGEX = re.compile(r'\A[0-9]+\Z')
+    DATETIME_REGEX = re.compile(
+        r'\A\d{4}-\d{1,2}-\d{1,2}\s\d{1,2}:\d{1,2}:\d{1,2}\Z')
+    PROMOTION_REGEX = re.compile(r'\A[a-zA-Z0-9]+\Z')
+
+    def __init__(self, client):
+        self.client = client
+
+    def _validate_id(self, value):
+        return value
+
+    def _validate_number(self, value):
+        return self._validate_id(value)
+
+    def _validate_present(self, value):
+        if not value:
+            raise Error("Required parameter is missing.")
+        return value
+
+    def _validate_user(self, value):
+        if value is None:
+            return None
+
+        if not isinstance(value, (int, str)):
+            raise Error(f"Invalid user id parameter: {value}")
+        return value
+
+    def _validate_datetime(self, value):
+        if isinstance(value, datetime):
+            return value.strftime("%Y-%m-%d %H:%M:%S")
+        if isinstance(value, str) and self.DATETIME_REGEX.match(value):
+            return value
+        raise Error(
+            f"Invalid datetime parameter: {value}. Provide a Time object or formatted 'YYYY-DD-MM%HH:MM:SS' string."
+            )
+
+    def _validate_options(self, value, options):
+        if value in options:
+            return value
+        raise Error(
+            f"Invalid option parameter: {value}. Must be one of {', '.join(options)}."
+        )
+
+    def _validate_promotion(self, value):
+        if not isinstance(value, str) or not value or not re.match(
+                self.PROMOTION_REGEX, value):
+            raise Error(
+                'Required parameter promotional code not found or contains other than alphanumeric characters.'
+            )
+        return value
+
+    def _validate_duplicate(self, value):
+        if not isinstance(value, str) or value not in ['ignore', 'raise']:
+            raise Error(
+                "Required parameter duplicate can only be 'ignore' or 'raise'."
+            )
+        return value
+
+    def _validate_notfound(self, value):
+        if not isinstance(value, str) or value not in ['error', 'ignore']:
+            raise Error(
+                "Required parameter notfound can only be 'error' or 'ignore'.")
+        return value

SuperSaaS/API/Forms.py

@@ -0,0 +1,31 @@
+from .BaseApi import BaseApi
+from ..Models.Form import Form
+from ..Models.SuperForm import SuperForm
+
+
+class Forms(BaseApi):
+
+    def get(self, form_id):
+        path = "/forms"
+        query = {'id': self._validate_id(form_id)}
+        res = self.client.get(path, query)
+        return Form(res)
+
+    def list(self, superform_id, from_time=None, user=None, limit=None, offset=None):
+        path = "/forms"
+        params = {'form_id': self._validate_id(superform_id)}
+        if from_time:
+            params['from'] = self._validate_datetime(from_time)
+        if user or user == 0:
+            params['user'] = self._validate_user(user)
+        if limit:
+            params['limit'] = self._validate_number(limit)
+        if offset:
+            params['offset'] = self._validate_number(offset)
+        res = self.client.get(path, params)
+        return [Form(attributes) for attributes in res]
+
+    def forms(self):
+        path = "/super_forms"
+        res = self.client.get(path)
+        return [SuperForm(attributes) for attributes in res]

SuperSaaS/API/Groups.py

@@ -0,0 +1,10 @@
+from .BaseApi import BaseApi
+from ..Models.Group import Group
+
+
+class Groups(BaseApi):
+
+    def list(self):
+        path = '/groups'
+        res = self.client.get(path)
+        return [Group(attributes) for attributes in res]

SuperSaaS/API/Hooks.py

@@ -0,0 +1,23 @@
+from .BaseApi import BaseApi
+
+
+class Hooks(BaseApi):
+    """Manage webhooks (`/api/hooks`)."""
+
+    def list(self):
+        return self.client.get('/hooks')
+
+    def create(self, target_url, event, parent_id):
+        params = {
+            'target_url': self._validate_present(target_url),
+            'event': self._validate_present(event),
+            'parent_id': self._validate_present(self._validate_id(parent_id))
+        }
+        return self.client.post('/hooks', params)
+
+    def delete(self, hook_id, parent_id):
+        query = {
+            'id': self._validate_present(self._validate_id(hook_id)),
+            'parent_id': self._validate_present(self._validate_id(parent_id))
+        }
+        return self.client.delete('/hooks', None, query)

SuperSaaS/API/Promotions.py

@@ -0,0 +1,32 @@
+from .BaseApi import BaseApi
+from ..Models.Promotion import Promotion
+
+
+class Promotions(BaseApi):
+
+    def list(self, limit=None, offset=None):
+        path = '/promotions'
+        params = {
+            'limit':
+            self._validate_number(limit) if limit is not None else None,
+            'offset':
+            self._validate_number(offset) if offset is not None else None
+        }
+        # Filter out None values, so Client.request does not append an empty "?" to the URL
+        params = {k: v for k, v in params.items() if v is not None}
+        res = self.client.get(path, params)
+        return [Promotion(attributes) for attributes in res]
+
+    def promotion(self, promotion_code):
+        path = '/promotions'
+        query = {'promotion_code': self._validate_promotion(promotion_code)}
+        res = self.client.get(path, query)
+        return [Promotion(attributes) for attributes in res]
+
+    def duplicate_promotion_code(self, promotion_code, template_code):
+        path = '/promotions'
+        query = {
+            'id': self._validate_promotion(promotion_code),
+            'template_code': self._validate_promotion(template_code)
+        }
+        self.client.post(path, query)

SuperSaaS/API/Schedules.py

@@ -0,0 +1,29 @@
+from .BaseApi import BaseApi
+from ..Models.Schedule import Schedule
+from ..Models.Resource import Resource
+from ..Models.FieldList import FieldList
+
+class Schedules(BaseApi):
+
+    def list(self):
+        path = "/schedules"
+        res = self.client.get(path)
+        return [Schedule(attributes) for attributes in res]
+
+    def resources(self, schedule_id):
+        query = {'schedule_id': self._validate_id(schedule_id)}
+        path = "/resources"
+        res = self.client.get(path, query)
+        return [Resource(attributes) for attributes in res]
+
+    def field_list(self, schedule_id):
+        path = '/field_list'
+        query = {'schedule_id': self._validate_id(schedule_id)}
+        res = self.client.get(path, query)
+        return [FieldList(attributes) for attributes in res]
+
+    def input_field_list(self, schedule_id):
+        path = '/input_field_list'
+        query = {'schedule_id': self._validate_id(schedule_id)}
+        res = self.client.get(path, query)
+        return [FieldList(attributes) for attributes in res]

SuperSaaS/API/Slots.py

@@ -0,0 +1,63 @@
+from .BaseApi import BaseApi
+from ..Models.Slot import Slot
+
+
+class Slots(BaseApi):
+    """Manage slots of capacity type schedules (`/api/slots`)."""
+
+    ATTRIBUTES = ('start', 'finish', 'title', 'description', 'location',
+                  'capacity', 'price', 'color')
+
+    def list(self, schedule_id, start_time=None, finish=None, limit=None, offset=None):
+        path = "/slots"
+        query = {
+            'schedule_id': self._validate_id(schedule_id),
+            'start':
+            self._validate_datetime(start_time) if start_time else None,
+            'finish': self._validate_datetime(finish) if finish else None,
+            'limit': self._validate_number(limit) if limit else None,
+            'offset': self._validate_number(offset) if offset else None
+        }
+        res = self.client.get(path, query)
+        return [Slot(attributes) for attributes in res]
+
+    def get(self, schedule_id, slot_id):
+        query = {'schedule_id': self._validate_id(schedule_id)}
+        path = self.__slot_path(slot_id)
+        res = self.client.get(path, query)
+        return Slot(res)
+
+    def create(self, schedule_id, attributes):
+        path = "/slots"
+        query = {'schedule_id': self._validate_id(schedule_id)}
+        res = self.client.post(path, self.__params(attributes), query)
+        return {'location': res}
+
+    def update(self, schedule_id, slot_id, attributes):
+        path = self.__slot_path(slot_id)
+        query = {'schedule_id': self._validate_id(schedule_id)}
+        return self.client.put(path, self.__params(attributes), query)
+
+    def delete(self, schedule_id, slot_id):
+        path = self.__slot_path(slot_id)
+        query = {'schedule_id': self._validate_id(schedule_id)}
+        return self.client.delete(path, None, query)
+
+    def __slot_path(self, slot_id):
+        return f"/slots/{self._validate_present(self._validate_id(slot_id))}"
+
+    def __params(self, attributes):
+        # Don't wrap attributes in 'slot' if they're already wrapped
+        if isinstance(attributes, dict) and 'slot' in attributes:
+            attributes = attributes['slot']
+        attributes = attributes or {}
+        slot = {}
+        for key in self.ATTRIBUTES:
+            value = attributes.get(key)
+            if key in ('start', 'finish') and value is not None:
+                value = self._validate_datetime(value)
+            # capacity: '-' means unlimited and 0 means no places. None values aren't sent, so
+            # capacity=None leaves the capacity unchanged instead of making it unlimited.
+            if value is not None:
+                slot[key] = value
+        return {'slot': slot}

SuperSaaS/API/Users.py

@@ -0,0 +1,98 @@
+from .BaseApi import BaseApi
+from ..Models.User import User
+from ..Models.FieldList import FieldList
+
+
+class Users(BaseApi):
+
+    def get(self, user_id=None, form=None):
+        path = self.__user_path(user_id)
+        query = {
+            'form': 'true' if form else None
+        }
+        res = self.client.get(path, query)
+        return User(res)
+
+    def list(self, form=None, limit=None, offset=None):
+        path = self.__user_path()
+        query = {
+            'form': 'true' if form else None,
+            'limit': self._validate_number(limit) if limit else None,
+            'offset': self._validate_number(offset) if offset else None
+        }
+        res = self.client.get(path, query)
+        return [User(attributes) for attributes in res]
+
+    def create(self, attributes, user_id=None, webhook=None, duplicate=None):
+        path = self.__user_path(user_id)
+        query = {'webhook': 'true' if webhook else None}
+        if duplicate:
+            query['duplicate'] = self._validate_duplicate(duplicate)
+        params = self.__params_for_update_create(attributes)
+        params['user'] = dict(
+            filter(lambda item: item[1] is not None, params['user'].items()))
+        res = self.client.post(path, params, query)
+        return {'location': res}
+
+    def update(self, user_id, attributes, webhook=None, notfound=None):
+        path = self.__user_path(user_id)
+        query = {'webhook': 'true' if webhook else None}
+        if notfound:
+            query['notfound'] = self._validate_notfound(notfound)
+        params = self.__params_for_update_create(attributes)
+        params['user'] = dict(
+            filter(lambda item: item[1] is not None, params['user'].items()))
+        return self.client.put(path, params, query)
+
+    def delete(self, user_id, webhook=None):
+        path = self.__user_path(self._validate_id(user_id))
+        query = {'webhook': 'true'} if webhook else None
+        return self.client.delete(path, None, query)
+
+    def field_list(self):
+        path = '/field_list'
+        res = self.client.get(path)
+        return [FieldList(attributes) for attributes in res]
+
+    def input_field_list(self):
+        path = '/input_field_list'
+        res = self.client.get(path)
+        return [FieldList(attributes) for attributes in res]
+
+    def __user_path(self, user_id=None):
+        return f"/users/{user_id}" if user_id else "/users"
+
+    def __params_for_update_create(self, attributes):
+        return {
+            'user': {
+                'name':
+                self._validate_present(attributes.get('name', ''))
+                if attributes.get('name', '') else None,
+                'email':
+                attributes.get('email', None),
+                'password':
+                attributes.get('password', None),
+                'full_name':
+                attributes.get('full_name', None),
+                'address':
+                attributes.get('address', None),
+                'mobile':
+                attributes.get('mobile', None),
+                'phone':
+                attributes.get('phone', None),
+                'country':
+                attributes.get('country', None),
+                'field_1':
+                attributes.get('field_1', None),
+                'field_2':
+                attributes.get('field_2', None),
+                'super_field':
+                attributes.get('super_field', None),
+                'credit':
+                attributes.get('credit', None),
+                'role':
+                attributes.get('role', None),
+                'group':
+                attributes.get('group', None)
+            }
+        }

SuperSaaS/API/__init__.py

@@ -0,0 +1,14 @@
+__all__ = [
+    "BaseApi", "Appointments", "Slots", "Forms", "Users", "Schedules", "Promotions",
+    "Groups", "Hooks"
+]
+
+from .BaseApi import BaseApi
+from .Appointments import Appointments
+from .Slots import Slots
+from .Forms import Forms
+from .Users import Users
+from .Schedules import Schedules
+from .Promotions import Promotions
+from .Groups import Groups
+from .Hooks import Hooks