supersaas-api-client 2.0.4 → 2.1.0

data/lib/supersaas-api-client/api/appointments.rb

@@ -3,10 +3,10 @@
 module Supersaas
   # REF: https://www.supersaas.com/info/dev/appointment_api
   class Appointments < BaseApi
-    def agenda(schedule_id, user_id, from_time = nil, slot = false)
+    def agenda(schedule_id, user, from_time = nil, slot = false)
       path = "/agenda/#{validate_id(schedule_id)}"
       params = {
-        user: validate_present(user_id),
+        user: validate_present(user),
         from: from_time && validate_datetime(from_time)
       }
       params.merge!(slot: true) if slot
@@ -14,6 +14,7 @@ module Supersaas
       map_slots_or_bookings(res)
     end
 
+    # LEGACY METHOD WILL BE REMOVED USE AGENDA
     def agenda_slots(schedule_id, user_id, from_time = nil)
       path = "/agenda/#{validate_id(schedule_id)}"
       params = {
@@ -38,14 +39,16 @@ module Supersaas
       map_slots_or_bookings(res)
     end
 
-    def list(schedule_id, form = nil, start_time = nil, limit = nil)
+    def list(schedule_id, form = nil, start_time = nil, limit = nil, finish = nil, offset = nil)
       path = '/bookings'
       params = {
         schedule_id: validate_id(schedule_id),
         form: form ? true : nil,
-        start: start_time ? validate_datetime(start_time) : nil
+        start: start_time ? validate_datetime(start_time) : nil,
+        finish: finish ? validate_datetime(finish) : nil
       }
       params.merge!(limit: validate_number(limit)) if limit
+      params.merge!(offset: validate_number(offset)) if offset
       res = client.get(path, params)
       map_slots_or_bookings(res)
     end
@@ -64,24 +67,7 @@ module Supersaas
         webhook: webhook,
         user_id: validate_id(user_id),
         form: form ? true : nil,
-        booking: {
-          start: attributes[:start],
-          finish: attributes[:finish],
-          name: attributes[:name],
-          email: attributes[:email],
-          full_name: attributes[:full_name],
-          address: attributes[:address],
-          mobile: attributes[:mobile],
-          phone: attributes[:phone],
-          country: attributes[:country],
-          field_1: attributes[:field_1],
-          field_2: attributes[:field_2],
-          field_1_r: attributes[:field_1_r],
-          field_2_r: attributes[:field_2_r],
-          super_field: attributes[:super_field],
-          resource_id: attributes[:resource_id],
-          slot_id: attributes[:slot_id]
-        }
+        booking: booking_params(attributes)
       }
       params[:booking].compact!
       client.post(path, params)
@@ -91,24 +77,7 @@ module Supersaas
       path = "/bookings/#{validate_id(appointment_id)}"
       params = {
         schedule_id: schedule_id,
-        booking: {
-          start: attributes[:start],
-          finish: attributes[:finish],
-          name: attributes[:name],
-          email: attributes[:email],
-          full_name: attributes[:full_name],
-          address: attributes[:address],
-          mobile: attributes[:mobile],
-          phone: attributes[:phone],
-          country: attributes[:country],
-          field_1: attributes[:field_1],
-          field_2: attributes[:field_2],
-          field_1_r: attributes[:field_1_r],
-          field_2_r: attributes[:field_2_r],
-          super_field: attributes[:super_field],
-          resource_id: attributes[:resource_id],
-          slot_id: attributes[:slot_id]
-        }
+        booking: booking_params(attributes)
       }
 
       params.merge!(form: form) if form
@@ -117,9 +86,10 @@ module Supersaas
       client.put(path, params)
     end
 
-    def delete(schedule_id, appointment_id)
+    def delete(schedule_id, appointment_id, webhook = nil)
       path = "/bookings/#{validate_id(appointment_id)}"
       params = { schedule_id: validate_id(schedule_id) }
+      params.merge!(webhook: webhook) if webhook
       client.delete(path, nil, params)
     end
 
@@ -130,8 +100,8 @@ module Supersaas
       map_slots_or_bookings(res)
     end
 
-    def range(schedule_id, today = false, from_time = nil, to = nil, slot = false, user = nil, resource_id = nil, service_id = nil,
-              limit = nil, offset = nil)
+    def range(schedule_id, today = false, from_time = nil, to = nil, slot = false, user = nil, resource_id = nil,
+              service_id = nil, limit = nil, offset = nil)
       path = "/range/#{validate_id(schedule_id)}"
       params = {}
       params = build_param(params, from_time, to, slot, user, limit, offset, resource_id, service_id)
@@ -142,6 +112,31 @@ module Supersaas
 
     private
 
+    # Input attributes only. description is for resource schedules, quantity (number of places) for capacity schedules, form_id attaches an existing form
+    def booking_params(attributes)
+      {
+        start: attributes[:start],
+        finish: attributes[:finish],
+        email: attributes[:email],
+        res_name: attributes[:name],
+        full_name: attributes[:full_name],
+        address: attributes[:address],
+        mobile: attributes[:mobile],
+        phone: attributes[:phone],
+        country: attributes[:country],
+        field_1: attributes[:field_1],
+        field_2: attributes[:field_2],
+        field_1_r: attributes[:field_1_r],
+        field_2_r: attributes[:field_2_r],
+        super_field: attributes[:super_field],
+        resource_id: attributes[:resource_id],
+        slot_id: attributes[:slot_id],
+        description: attributes[:description],
+        quantity: attributes[:quantity],
+        form_id: attributes[:form_id]
+      }
+    end
+
     def map_slots_or_bookings(obj, slot = false)
       if obj.is_a?(Array) && slot
         obj.map { |attributes| Supersaas::Slot.new(attributes) }

data/lib/supersaas-api-client/api/base_api.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'date'
+
 module Supersaas
   class BaseApi
     attr_accessor :client

data/lib/supersaas-api-client/api/forms.rb

@@ -3,11 +3,13 @@
 module Supersaas
   # REF: https://www.supersaas.com/info/dev/form_api
   class Forms < BaseApi
-    def list(template_form_id, from_time = nil, user = nil)
+    def list(template_form_id, from_time = nil, user = nil, limit = nil, offset = nil)
       path = '/forms'
       params = { form_id: validate_id(template_form_id) }
       params.merge!(from: validate_datetime(from_time)) if from_time
       params.merge!(user: validate_user(user)) if user
+      params.merge!(limit: limit) if limit
+      params.merge!(offset: offset) if offset
       res = client.get(path, params)
       res.map { |attributes| Supersaas::Form.new(attributes) }
     end

data/lib/supersaas-api-client/api/groups.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Supersaas
+  # REF: https://www.supersaas.com/info/dev/information_api#groups
   class Groups < BaseApi
-    # REF: https://www.supersaas.com/info/dev/information_api#groups
     def list
       path = '/groups'
       res = client.get(path)

data/lib/supersaas-api-client/api/hooks.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Supersaas
+  # REF: https://www.supersaas.com/info/dev/webhooks
+  class Hooks < BaseApi
+    # event: the trigger, e.g. 'U' (user created), 'M' (user changed), 'N' (new appointment), 'C' (changed appointment)
+    # parent_id: the schedule id for appointment events, the super form id for form events, else the account id
+    # Returns { 'id' => ..., 'parent_id' => ... }
+    def create(target_url, event, parent_id)
+      path = '/hooks'
+      params = {
+        target_url: validate_present(target_url),
+        event: validate_present(event),
+        parent_id: validate_id(parent_id)
+      }
+      client.post(path, params)
+    end
+
+    def delete(hook_id, parent_id)
+      path = '/hooks'
+      query = { id: validate_id(hook_id), parent_id: validate_id(parent_id) }
+      client.delete(path, nil, query)
+    end
+  end
+end

data/lib/supersaas-api-client/api/promotions.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Supersaas
+  # REF: https://www.supersaas.com/info/dev/promotion_api
   class Promotions < BaseApi
-    # REF: https://www.supersaas.com/info/dev/promotion_api
     def list(limit = nil, offset = nil)
       path = '/promotions'
       params = {}

data/lib/supersaas-api-client/api/schedules.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Supersaas
+  # REF: https://www.supersaas.com/info/dev/information_api
   class Schedules < BaseApi
-    # REF: https://www.supersaas.com/info/dev/information_api
     def list
       path = '/schedules'
       res = client.get(path)
@@ -22,5 +22,13 @@ module Supersaas
       res = client.get(path, query)
       res.map { |attributes| Supersaas::FieldList.new(attributes) }
     end
+
+    # The fields that can be set when creating a booking
+    def input_field_list(schedule_id)
+      path = '/input_field_list'
+      query = { schedule_id: validate_id(schedule_id) }
+      res = client.get(path, query)
+      res.map { |attributes| Supersaas::FieldList.new(attributes) }
+    end
   end
 end

data/lib/supersaas-api-client/api/slots.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Supersaas
+  # REF: https://www.supersaas.com/info/dev/appointment_api#slots_api
+  # Only available for capacity type schedules.
+  class Slots < BaseApi
+    def list(schedule_id, start_time = nil, finish = nil, limit = nil, offset = nil)
+      path = '/slots'
+      params = {
+        schedule_id: validate_id(schedule_id),
+        start: start_time ? validate_datetime(start_time) : nil,
+        finish: finish ? validate_datetime(finish) : nil
+      }
+      params.merge!(limit: validate_number(limit)) if limit
+      params.merge!(offset: validate_number(offset)) if offset
+      res = client.get(path, params)
+      res.map { |attributes| Supersaas::Slot.new(attributes) }
+    end
+
+    def get(schedule_id, slot_id)
+      params = { schedule_id: validate_id(schedule_id) }
+      path = "/slots/#{validate_id(slot_id)}"
+      res = client.get(path, params)
+      Supersaas::Slot.new(res)
+    end
+
+    def create(schedule_id, attributes)
+      path = '/slots'
+      query = { schedule_id: validate_id(schedule_id) }
+      client.post(path, { slot: slot_params(attributes) }, query)
+    end
+
+    def update(schedule_id, slot_id, attributes)
+      path = "/slots/#{validate_id(slot_id)}"
+      query = { schedule_id: validate_id(schedule_id) }
+      client.put(path, { slot: slot_params(attributes) }, query)
+    end
+
+    def delete(schedule_id, slot_id)
+      path = "/slots/#{validate_id(slot_id)}"
+      params = { schedule_id: validate_id(schedule_id) }
+      client.delete(path, nil, params)
+    end
+
+    private
+
+    # capacity: an Integer, or '-' for unlimited, '0' for no places
+    def slot_params(attributes)
+      params = {
+        start: attributes[:start] && validate_datetime(attributes[:start]),
+        finish: attributes[:finish] && validate_datetime(attributes[:finish]),
+        title: attributes[:title],
+        description: attributes[:description],
+        location: attributes[:location],
+        capacity: attributes[:capacity],
+        price: attributes[:price],
+        color: attributes[:color]
+      }
+      params.compact!
+      params
+    end
+  end
+end

data/lib/supersaas-api-client/api/users.rb

@@ -10,13 +10,17 @@ module Supersaas
         limit: limit && validate_number(limit),
         offset: offset && validate_number(offset)
       }
+      params.compact!
       res = client.get(path, params)
       res.map { |attributes| Supersaas::User.new(attributes) }
     end
 
-    def get(user_id)
+    def get(user_id, form = nil)
       path = user_path(user_id)
-      res = client.get(path)
+      params = {
+        form: form ? true : nil
+      }
+      res = client.get(path, params)
       Supersaas::User.new(res)
     end
 
@@ -24,24 +28,7 @@ module Supersaas
       path = user_path(user_id)
       query = { webhook: webhook }
       query.merge!(duplicate: validate_duplicate(duplicate)) if duplicate
-      params = {
-        user: {
-          name: validate_name(attributes[:name]),
-          email: attributes[:email],
-          password: attributes[:password],
-          full_name: attributes[:full_name],
-          address: attributes[:address],
-          mobile: attributes[:mobile],
-          phone: attributes[:phone],
-          country: attributes[:country],
-          timezone: attributes[:timezone],
-          field_1: attributes[:field_1],
-          field_2: attributes[:field_2],
-          super_field: attributes[:super_field],
-          credit: attributes[:credit] && validate_number(attributes[:credit]),
-          role: attributes[:role] && validate_options(attributes[:role], User::ROLES)
-        }
-      }
+      params = { user: user_params(attributes) }
       client.post(path, params, query)
     end
 
@@ -49,31 +36,14 @@ module Supersaas
       path = user_path(user_id)
       query = { webhook: webhook }
       query.merge!(notfound: validate_notfound(notfound)) if notfound
-      params = {
-        user: {
-          name: validate_name(attributes[:name]),
-          email: attributes[:email],
-          password: attributes[:password],
-          full_name: attributes[:full_name],
-          address: attributes[:address],
-          mobile: attributes[:mobile],
-          phone: attributes[:phone],
-          country: attributes[:country],
-          timezone: attributes[:timezone],
-          field_1: attributes[:field_1],
-          field_2: attributes[:field_2],
-          super_field: attributes[:super_field],
-          credit: attributes[:credit] && validate_number(attributes[:credit]),
-          role: attributes[:role] && validate_options(attributes[:role], User::ROLES)
-        }
-      }
-      params[:user].compact!
+      params = { user: user_params(attributes) }
       client.put(path, params, query)
     end
 
-    def delete(user_id)
+    def delete(user_id, webhook = nil)
       path = user_path(user_id)
-      client.delete(path)
+      params = { webhook: webhook }
+      client.delete(path, nil, params)
     end
 
     def field_list
@@ -82,6 +52,13 @@ module Supersaas
       res.map { |attributes| Supersaas::FieldList.new(attributes) }
     end
 
+    # The fields that can be set when creating a user
+    def input_field_list
+      path = '/input_field_list'
+      res = client.get(path)
+      res.map { |attributes| Supersaas::FieldList.new(attributes) }
+    end
+
     private
 
     def user_path(user_id)
@@ -91,5 +68,26 @@ module Supersaas
         "/users/#{validate_user(user_id)}"
       end
     end
+
+    # The user attributes the API accepts, leaving out the ones that are nil
+    def user_params(attributes)
+      {
+        name: validate_name(attributes[:name]),
+        email: attributes[:email],
+        password: attributes[:password],
+        full_name: attributes[:full_name],
+        address: attributes[:address],
+        mobile: attributes[:mobile],
+        phone: attributes[:phone],
+        country: attributes[:country],
+        timezone: attributes[:timezone],
+        field_1: attributes[:field_1],
+        field_2: attributes[:field_2],
+        super_field: attributes[:super_field],
+        credit: attributes[:credit] && validate_number(attributes[:credit]),
+        role: attributes[:role] && validate_options(attributes[:role], User::ROLES),
+        group: attributes[:group] && validate_number(attributes[:group])
+      }.compact
+    end
   end
 end

data/lib/supersaas-api-client/client.rb

@@ -47,6 +47,10 @@ module Supersaas
       @schedules ||= Schedules.new(self)
     end
 
+    def slots
+      @slots ||= Slots.new(self)
+    end
+
     def users
       @users ||= Users.new(self)
     end
@@ -59,6 +63,16 @@ module Supersaas
       @groups ||= Groups.new(self)
     end
 
+    def hooks
+      @hooks ||= Hooks.new(self)
+    end
+
+    # Checks the credentials, returns true or raises Supersaas::Exception
+    def ping
+      get('/ping')
+      true
+    end
+
     def get(path, query = {})
       request(:get, path, {}, query)
     end
@@ -77,12 +91,14 @@ module Supersaas
 
     private
 
-    # The rate limiter allows a maximum of 4 requests within the specified time window
+    # The rate limiter allows at most MAX_REQUESTS requests per WINDOW_SIZE seconds
     WINDOW_SIZE = 1 # seconds
-    MAX_PER_WINDOW = 4
+    MAX_REQUESTS = 4
+
     def throttle
       # A queue to store timestamps of requests made within the rate limiting window
-      @queue ||= Array.new(MAX_PER_WINDOW)
+      @queue ||= Array.new(MAX_REQUESTS)
+
       # Represents the timestamp of the oldest request within the time window
       oldest_request = @queue.push(Time.now).shift
       # This ensures that the client does not make requests faster than the defined rate limit
@@ -136,7 +152,7 @@ module Supersaas
       if verbose
         puts '### SuperSaaS Client Request:'
         puts "#{http_method} #{path}"
-        puts params.to_json
+        puts filter_secrets(params).to_json
         puts '------------------------------'
       end
 
@@ -159,6 +175,8 @@ module Supersaas
 
       code = res.code.to_i
       case code
+      when 204
+        {}
       when 200, 201
         if http_method == :post && res['location'] =~ /www.supersaas.com/
           res['location']
@@ -171,34 +189,24 @@ module Supersaas
     end
 
     def handle_errors(code, res)
-      print_errors(res)
-      case code
-      when 422
-        raise Supersaas::Exception, 'HTTP Request Error: Unprocessable Content'
-      when 400
-        raise Supersaas::Exception, 'HTTP Request Error: Bad Request'
-      when 401
-        raise Supersaas::Exception, 'HTTP Request Error: Unauthorised'
-      when 404
-        raise Supersaas::Exception, 'HTTP Request Error: Not Found'
-      when 501
-        raise Supersaas::Exception, 'Not yet implemented for service type schedule'
-      when 403
-        raise Supersaas::Exception, 'Unauthorized'
-      when 405
-        raise Supersaas::Exception, 'Not available for capacity type schedule'
-      else
-        raise Supersaas::Exception, "HTTP Request Error: #{code}"
-      end
-    end
-
-    def print_errors(res)
-      json_body = json_body(res)
-      return unless json_body[:errors]
-
-      errors each do |error|
-        puts "Error code: #{error['code']}, #{error['title']}"
-      end
+      message = case code
+                when 422 then 'HTTP Request Error: Unprocessable Content'
+                when 400 then 'HTTP Request Error: Bad Request'
+                when 401 then 'HTTP Request Error: Unauthorised'
+                when 404 then 'HTTP Request Error: Not Found'
+                when 501 then 'Not yet implemented for service type schedule'
+                when 403 then 'Unauthorized'
+                when 405 then 'Not available for this schedule type'
+                else "HTTP Request Error: #{code}"
+                end
+      raise Supersaas::Exception.new(message, status: code, errors: parsed_errors(res))
+    end
+
+    # The errors array of a JSON error body like {"errors":[{"status":"404","title":"Not found"}]}
+    def parsed_errors(res)
+      body = json_body(res)
+      errors = body['errors'] if body.is_a?(Hash)
+      errors.is_a?(Array) ? errors : []
     end
 
     def json_body(res)
@@ -216,6 +224,14 @@ module Supersaas
       end
     end
 
+    # A copy of the params with password values replaced, for verbose output only
+    def filter_secrets(value)
+      return value.map { |v| filter_secrets(v) } if value.is_a?(Array)
+      return value unless value.is_a?(Hash)
+
+      value.each_with_object({}) { |(k, v), h| h[k] = k.to_s == 'password' ? '[FILTERED]' : filter_secrets(v) }
+    end
+
     class Configuration
       DEFAULT_HOST = 'https://www.supersaas.com'
 

data/lib/supersaas-api-client/exception.rb

@@ -6,5 +6,13 @@ module Supersaas
     @code = nil
 
     attr_accessor :field, :code
+    # HTTP status code and the server's parsed errors, e.g. [{"status"=>"404", "title"=>"Not found"}]
+    attr_reader :status, :errors
+
+    def initialize(message = nil, status: nil, errors: [])
+      super(message)
+      @status = status
+      @errors = errors
+    end
   end
 end

data/lib/supersaas-api-client/models/appointment.rb

@@ -2,10 +2,11 @@
 
 module Supersaas
   class Appointment < BaseModel
-    attr_accessor :address, :country, :created_by, :created_on, :deleted, :description, :email, :field_1, :field_2,
-                  :field_1_r, :field_2_r, :finish, :form_id, :full_name, :id, :mobile, :name, :phone, :price, :res_name,
-                  :resource_id, :schedule_id, :schedule_name, :service_id, :service_name, :slot_id, :start, :status,
-                  :super_field, :updated_by, :updated_on, :user_id, :waitlisted
+    attr_accessor :field_1, :field_2, :field_2_r, :field_1_r, :country, :address, :mobile, :phone, :email, :price_cents,
+                  :finish, :start, :service_name, :res_name, :id, :quantity, :status_message, :deleted,
+                  :created_on, :slot_id, :created_by, :price, :status, :full_name, :super_field, :updated_by, :form_id,
+                  :updated_on, :user_id, :waitlisted, :resource_id, :schedule_name, :schedule_id, :service_id
+
     attr_reader :form, :slot
 
     def form=(value)

data/lib/supersaas-api-client/models/base_model.rb

@@ -10,12 +10,28 @@ module Supersaas
       assign_attributes(attributes)
     end
 
+    # Hash-style access to the raw attribute value, with a String or Symbol key.
+    # Keeps code working that read nested data as a Hash, e.g. appointment.form['content'].
+    def [](key)
+      return attributes[key] if attributes.key?(key)
+
+      case key
+      when Symbol then attributes[key.to_s]
+      when String then attributes[key.to_sym]
+      end
+    end
+
+    def to_h
+      attributes.to_h
+    end
+
     private
 
     def assign_attributes(attributes)
       attributes.each do |key, value|
-        self.class.module_eval { attr_accessor key }
-        public_send("#{key}=", value) if respond_to?("#{key}=")
+        # Keep custom writers such as Appointment#form=, which wrap nested data in models
+        self.class.module_eval { attr_accessor key } unless self.class.method_defined?("#{key}=")
+        public_send("#{key}=", value)
       end
     end
   end

data/lib/supersaas-api-client/models/field_list.rb

@@ -2,11 +2,20 @@
 
 module Supersaas
   class FieldList < BaseModel
-    attr_accessor :name, :type, :label, :advanced
+    attr_accessor :name, :type, :label, :advanced, :required
     attr_reader :spec
 
     def spec=(value)
-      @spec = value.is_a?(Array) ? value.map { |attributes| JSON.parse(attributes) } : value
+      @spec = value.is_a?(Array) ? value.map { |item| parse_spec_item(item) } : value
+    end
+
+    private
+
+    # Items arrive as JSON strings; anything else (or invalid JSON) is kept as is
+    def parse_spec_item(item)
+      item.is_a?(String) ? JSON.parse(item) : item
+    rescue JSON::ParserError
+      item
     end
   end
 end

data/lib/supersaas-api-client/models/form.rb

@@ -2,7 +2,6 @@
 
 module Supersaas
   class Form < BaseModel
-    attr_accessor :content, :created_on, :deleted, :id, :reservation_process_id, :super_form_id, :uniq, :updated_name,
-                  :updated_on, :user_id
+    attr_accessor :content, :created_on, :deleted, :id, :reservation_process_id, :super_form_id, :updated_on, :user_id
   end
 end

data/lib/supersaas-api-client/models/slot.rb

@@ -2,7 +2,7 @@
 
 module Supersaas
   class Slot < BaseModel
-    attr_accessor :count, :description, :finish, :id, :location, :name, :start, :title
+    attr_accessor :capacity, :color, :count, :description, :finish, :id, :location, :name, :price, :start, :title
     attr_reader :bookings
 
     def bookings=(value)

data/lib/supersaas-api-client/models/user.rb

@@ -5,6 +5,8 @@ module Supersaas
     ROLES = [3, 4, -1].freeze
 
     attr_reader :form
+    attr_accessor :name, :email, :password, :full_name, :address, :mobile, :phone, :country, :timezone, :field_1,
+                  :field_2, :super_field, :credit, :role, :group, :webhook, :id, :fk, :created_on, :updated_on
 
     def form=(value)
       @form = value.is_a?(Hash) ? Supersaas::Form.new(value) : value