supersaas-api-client 2.0.5 → 2.1.0

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

@@ -67,24 +67,7 @@ module Supersaas
         webhook: webhook,
         user_id: validate_id(user_id),
         form: form ? true : nil,
-        booking: {
-          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]
-        }
+        booking: booking_params(attributes)
       }
       params[:booking].compact!
       client.post(path, params)
@@ -94,24 +77,7 @@ module Supersaas
       path = "/bookings/#{validate_id(appointment_id)}"
       params = {
         schedule_id: schedule_id,
-        booking: {
-          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]
-        }
+        booking: booking_params(attributes)
       }
 
       params.merge!(form: form) if form
@@ -146,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/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

@@ -28,26 +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),
-          group: attributes[:group] && validate_number(attributes[:group])
-        }
-      }
-      params[:user].compact!
+      params = { user: user_params(attributes) }
       client.post(path, params, query)
     end
 
@@ -55,26 +36,7 @@ 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),
-          group: attributes[:group] && validate_number(attributes[:group])
-        }
-      }
-      params[:user].compact!
+      params = { user: user_params(attributes) }
       client.put(path, params, query)
     end
 
@@ -90,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)
@@ -99,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,7 +91,7 @@ module Supersaas
 
     private
 
-    # The rate limiter allows a maximum of 1 requests within the specified time window
+    # The rate limiter allows at most MAX_REQUESTS requests per WINDOW_SIZE seconds
     WINDOW_SIZE = 1 # seconds
     MAX_REQUESTS = 4
 
@@ -138,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
 
@@ -161,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']
@@ -173,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)
@@ -218,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/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/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/version.rb

@@ -2,5 +2,5 @@
 
 module Supersaas
   API_VERSION = '3'
-  VERSION = '2.0.5'
+  VERSION = '2.1.0'
 end

data/lib/supersaas.rb

@@ -17,7 +17,9 @@ require 'supersaas-api-client/api/base_api'
 require 'supersaas-api-client/api/appointments'
 require 'supersaas-api-client/api/forms'
 require 'supersaas-api-client/api/schedules'
+require 'supersaas-api-client/api/slots'
 require 'supersaas-api-client/api/groups'
+require 'supersaas-api-client/api/hooks'
 require 'supersaas-api-client/api/promotions'
 require 'supersaas-api-client/api/users'
 require 'supersaas-api-client/client'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: supersaas-api-client
 version: !ruby/object:Gem::Version
-  version: 2.0.5
+  version: 2.1.0
 platform: ruby
 authors:
 - Kaarle Kulvik
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-01-26 00:00:00.000000000 Z
+date: 2026-11-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -70,36 +70,28 @@ description: Online appointment scheduling for any type of business. Flexible an
   affordable booking software that can be integrated into any site. Free basic version.
 email:
 - kaarle@supersaas.com
-executables:
-- console
-- setup
+executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".github/workflows/actions.yaml"
-- ".gitignore"
-- ".rubocop.yml"
-- ".rubocop_todo.yml"
-- Gemfile
-- Gemfile.lock
 - LICENSE
 - README.md
-- Rakefile
-- bin/console
-- bin/setup
 - examples/appointments.rb
 - examples/forms.rb
 - examples/groups.rb
 - examples/promotions.rb
 - examples/schedules.rb
+- examples/slots.rb
 - examples/users.rb
 - lib/supersaas-api-client.rb
 - lib/supersaas-api-client/api/appointments.rb
 - lib/supersaas-api-client/api/base_api.rb
 - lib/supersaas-api-client/api/forms.rb
 - lib/supersaas-api-client/api/groups.rb
+- lib/supersaas-api-client/api/hooks.rb
 - lib/supersaas-api-client/api/promotions.rb
 - lib/supersaas-api-client/api/schedules.rb
+- lib/supersaas-api-client/api/slots.rb
 - lib/supersaas-api-client/api/users.rb
 - lib/supersaas-api-client/client.rb
 - lib/supersaas-api-client/exception.rb
@@ -116,11 +108,13 @@ files:
 - lib/supersaas-api-client/models/user.rb
 - lib/supersaas-api-client/version.rb
 - lib/supersaas.rb
-- supersaas-api-client.gemspec
 homepage: https://www.supersaas.com
 licenses:
 - MIT
 metadata:
+  source_code_uri: https://github.com/SuperSaaS/supersaas-ruby-api-client
+  bug_tracker_uri: https://github.com/SuperSaaS/supersaas-ruby-api-client/issues
+  documentation_uri: https://www.supersaas.com/info/dev
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -130,14 +124,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Manage appointments and users on the SuperSaaS scheduling platform

data/.github/workflows/actions.yaml

@@ -1,21 +0,0 @@
-name: SuperSaaS Ruby API Client CI
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
-jobs:
-  test:
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macos-latest]
-        ruby: ['3.0', '3.1', '3.2', '3.3', 'head', 'jruby', 'jruby-head']
-    runs-on: ${{ matrix.os }}
-    steps:
-    - uses: actions/checkout@v2
-    - uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ matrix.ruby }}
-        bundler-cache: true
-    - run: bundle exec rake

data/.gitignore

@@ -1,13 +0,0 @@
-/.bundle/
-/.yardoc
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
-/supersaas-api-client/
-.DS_Store
-.idea/*
-*.gem
-*.swp

data/.rubocop.yml

@@ -1 +0,0 @@
-inherit_from: .rubocop_todo.yml