supersaas-api-client 2.0.5 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c1167242f50872bf5bcce7d66d0e66af3f5ce2e6e90d9c14142c5c41536b83c
-  data.tar.gz: 3e93e114c2778055521baa9aa0828d3dd01ad9409af0796f60f22d0a55c20ff3
+  metadata.gz: 48f5cb476c043a4a2af0c8074ca7458d742ab825ae4da26075c9451b536dd985
+  data.tar.gz: 2a0ea6698b74279c1533272a094ddd2c31ebcffcb9d8cfe33c4fcd27f0ae3f43
 SHA512:
-  metadata.gz: f530da06419d03c7eba52a8a8fe8971e70d6aad06ea71e99d612c6cf1954ff66e8737bf2c26e77c447fb28f19a032f98637d0ee5a0698d6649ee3581b15ef214
-  data.tar.gz: 159298164a8e0b4af53a7c424495d3a8752edac213068aaa30c87fb53546d9b93069fa924f98a35c00d34d73c4d125043aa78fef854271ad5fa9585332ee3186
+  metadata.gz: 12fe85acf084b75321a21b1f1c91bddbcda6bc97496c9eadb89f66ed0c469bdf5e62dacf9dfd0842957a3e7b3afb73ad2516a7b76ef2a7eee752b9a93cc5270e
+  data.tar.gz: e347315a16264c7d5c3f8a06b124169aa55dfe8b0bfc44c232e5a3122ea6ee2588fa25809b15c76846fca0c040f0ae228381ef62815856f017332ff9e0e45355

data/README.md

@@ -1,9 +1,9 @@
 # SuperSaaS Ruby API Client
 
-Manage appointments, users, and other object on the [SuperSaaS appointment scheduling](https://www.supersaas.com/) platform in Ruby.
+Manage appointments, users, and other objects on the [SuperSaaS appointment scheduling](https://www.supersaas.com/) platform in Ruby.
 
-The SuperSaaS API provides endpoints that can be used to read or update information from your SuperSaaS account. 
-This can be useful to build an integration with back-end system or to extract information to generate reports.
+The SuperSaaS API provides endpoints that can be used to read or update information from your SuperSaaS account.
+This can be useful to build an integration with a back-end system or to extract information to generate reports.
 
 ## Prerequisites
 
@@ -12,7 +12,7 @@ This can be useful to build an integration with back-end system or to extract in
 
 ### Dependencies
 
-No external dependencies. Only the `json` and `net/http` gems from the ruby standard library are used.
+No external dependencies. Only the `json` and `net/http` libraries from the Ruby standard library are used. Requires Ruby 2.5 or later.
 
 ## Installation
 
@@ -20,7 +20,7 @@ Install with:
 
     $ gem install supersaas-api-client
 
-Alternatively, you can use `bundler` to install it by adding this line to you Gemfile. 
+Alternatively, you can use `bundler` to install it by adding this line to your Gemfile.
 The supersaas-api-client may update major versions with breaking changes, so it's recommended to use a major version when expressing the gem dependency. e.g.
 
     gem 'supersaas-api-client', '~> 2'
@@ -28,11 +28,11 @@ The supersaas-api-client may update major versions with breaking changes, so it'
 ## Configuration
 
 The `Client` can be used either (1) through the singleton helper method `instance`, e.g.
-    
+
     Supersaas::Client.instance #=> <Supersaas::Client>
-    
+
 Or else by (2) simply creating a new client instance manually, e.g.
-    
+
     Supersaas::Client.new #=> <Supersaas::Client>
 
 Initialize the SuperSaaS `Client` with authorization credentials:
@@ -41,19 +41,19 @@ Initialize the SuperSaaS `Client` with authorization credentials:
       config.account_name = 'accnt'
       config.api_key = 'xxxxxxxxxxxxxxxxxxxxxx'
     end
-    
+
 > Note, ensure that `configure` is called before `instance` or `new`, otherwise the client will be initialized with configuration defaults.
 
 If the client isn't configured explicitly, it will use default `ENV` variables for the account name and api key.
 
     ENV['SSS_API_ACCOUNT_NAME'] = 'your-env-supersaas-account-name'
-    ENV['SSS_API_KEY'] = 'your-env-supersaas-account-name' 
+    ENV['SSS_API_KEY'] = 'your-env-supersaas-api-key'
     Supersaas::Client.instance.account_name #=> 'your-env-supersaas-account-name'
-    Supersaas::Client.instance.api_key #=> 'your-env-supersaas-account-name'
-    
+    Supersaas::Client.instance.api_key #=> 'your-env-supersaas-api-key'
+
 All configuration options can be individually set on the client.
 
-    Supersaas::Client.instance.api_key = 'xxxxxxxxxxxxxxxxxxxxxx' 
+    Supersaas::Client.instance.api_key = 'xxxxxxxxxxxxxxxxxxxxxx'
     Supersaas::Client.instance.verbose = true
     ...
 
@@ -69,7 +69,7 @@ Create a user with user attributes params `create(attributes, user_id = nil, web
 If webhook=true is present it will trigger any webhooks connected to the account.
 To avoid a ‘create’ action from being automatically interpreted as an ‘update’, you can add the parameter duplicate=raise, then error `422 Unprocessable Entity` will be raised.
 If in your database your user has id 1234 then you can supply a foreign key in format 1234fk in `user_id` (optional) which you can use to identify user:
-If validation fails for any field then error `422 Unprocessable Entity` will be raised and any additional information will be printed to your log.
+If validation fails for any field then error `422 Unprocessable Entity` will be raised. The server's explanation is in the exception's `errors`, see [Error Handling](#error-handling).
 Data fields that you can supply can be found [here.](https://www.supersaas.com/info/dev/user_api)
 
     Supersaas::Client.instance.users.create({name: 'name@name.com', full_name: 'Example Name', email: 'example@example.com'}, '1234fk', true, 'raise') #=> http://www.supersaas.com/api/users/1234.json
@@ -83,14 +83,14 @@ If the `user_id` does not exist 404 error will be raised.
 You only need to specify the attributes you wish to update:
 
     Supersaas::Client.instance.users.update(12345, {full_name: 'New Name'}, true, "ignore") #=> nil
-    
+
 #### Delete User
 
 Delete a single user by `user_id`, and if the user does not exist 404 error will be raised.
 If webhook=true is present it will trigger any webhooks connected to the account.
 
     Supersaas::Client.instance.users.delete(12345) #=> nil
-    
+
 #### Get User
 
 Get a single user by `user_id`, and if the user does not exist 404 error will be raised, you may use optional `form`:
@@ -110,6 +110,12 @@ Get all the fields available to user object:
 
     Supersaas::Client.instance.users.field_list #=> [<Supersaas::FieldList>, ...]
 
+#### List Input Fields of User object
+
+Get the fields that can be set when creating a user, each with a `required` flag:
+
+    Supersaas::Client.instance.users.input_field_list #=> [<Supersaas::FieldList>, ...]
+
 #### Create Appointment/Booking
 
 Create an appointment with `schedule_id`, and `user_id(optional)` (see API documentation on [create new](https://www.supersaas.com/info/dev/appointment_api#bookings_api)) appointment attributes and optional `form` and `webhook` params,
@@ -117,6 +123,10 @@ Create an appointment with `schedule_id`, and `user_id(optional)` (see API docum
 
     Supersaas::Client.instance.appointments.create(12345, 67890, {full_name: 'Example Name', email: 'example@example.com', slot_id: 12345}, true, true) #=> http://www.supersaas.com/api/bookings/12345.json
 
+**Input attributes** are sent on create and update: `start`, `finish`, `name`, `full_name`, `email`, `address`, `mobile`, `phone`, `country`, `field_1`, `field_2`, `field_1_r`, `field_2_r`, `super_field`, `description` and `form_id`, plus what is booked: `resource_id` on a resource schedule, or `slot_id` and `quantity` (number of places) on a capacity schedule. Any other attribute is not sent. The API does not support creating bookings on service schedules.
+
+**Read-only attributes** are returned when reading appointments but never sent: `id`, `created_on`, `updated_on`, `created_by`, `updated_by`, `user_id`, `deleted`, `res_name`, `service_id`, `service_name`, `waitlisted`, and `form` when reading with `form` set.
+
 #### Update Appointment/Booking
 
 Update an appointment by `schedule_id` and `appointment_id` with appointment attributes, see the above link,
@@ -138,14 +148,14 @@ Get a single appointment by `schedule_id` and `appointment_id`:
 
 #### List Appointments/Bookings
 
-List appointments by `schedule_id`, with `form` and `start_time` and `limit` view params,
-`list(schedule_id, form = nil, start_time = nil, limit = nil)`:
+List appointments by `schedule_id`, with `form`, `start_time`, `limit`, `finish` and `offset` view params,
+`list(schedule_id, form = nil, start_time = nil, limit = nil, finish = nil, offset = nil)`:
 
-    Supersaas::Client.instance.appointments.list(12345, 67890, true, true) #=> [<Supersaas::Appointment>, ...]
+    Supersaas::Client.instance.appointments.list(12345, true, '2018-01-31 00:00:00', 25) #=> [<Supersaas::Appointment>, ...]
 
 #### Get Agenda
 
-Get agenda (upcoming) appointments by `schedule_id` and `user_id`, with `from_time` view param ([see](https://www.supersaas.com/info/dev/appointment_api#agenda),
+Get agenda (upcoming) appointments by `schedule_id` and `user_id`, with `from_time` view param ([see](https://www.supersaas.com/info/dev/appointment_api#agenda)),
 `agenda(schedule_id, user_id, from_time = nil, slot = false)`:
 
     Supersaas::Client.instance.appointments.agenda(12345, 67890, '2018-01-31 00:00:00') #=> [<Supersaas::Appointment>, ...]
@@ -156,13 +166,13 @@ This method is deprecated and will be removed in the future.
 Get agenda (upcoming) slots by `schedule_id` and `user_id`, with `from_time` view param,
 `agenda_slots(schedule_id, user_id, from_time = nil)`:
 
-    Supersaas::Client.instance.appointments.agenda_slots(12345, 67890, '2018-01-31 00:00:00') #=> [<Supersaas::Slot>, ...]    
+    Supersaas::Client.instance.appointments.agenda_slots(12345, 67890, '2018-01-31 00:00:00') #=> [<Supersaas::Slot>, ...]
 
 _Note: only works for capacity type schedules._
 
 #### Get Available Appointments/Bookings
 
-Get available appointments by `schedule_id`, with `from` time and `length_minutes` and `resource` params ([see](https://www.supersaas.com/info/dev/appointment_api#availability_api),
+Get available appointments by `schedule_id`, with `from` time and `length_minutes` and `resource` params ([see](https://www.supersaas.com/info/dev/appointment_api#availability_api)),
 `available(schedule_id, from_time, length_minutes = nil, resource = nil, full = nil, limit = nil)`:
 
     Supersaas::Client.instance.appointments.available(12345, '2018-01-31 00:00:00', 15, 'My Class') #=> [<Supersaas::Appointment>, ...]
@@ -172,7 +182,7 @@ Get available appointments by `schedule_id`, with `from` time and `length_minute
 Get recently changed appointments by `schedule_id`, with `from` time, `to` time, `user` user, `slot` view params (see [docs](https://www.supersaas.com/info/dev/appointment_api#recent_changes)),
 `changes(schedule_id, from_time = nil, to = nil, slot = false, user = nil, limit = nil, offset = nil)`:
 
-    Supersaas::Client.instance.appointments.changes(12345, '2018-01-31 00:00:00', '2019-01-31 00:00:00',  true) #=> [<Supersaas::Appointment>, ...]
+    Supersaas::Client.instance.appointments.changes(12345, '2018-01-31 00:00:00', '2019-01-31 00:00:00', true) #=> [<Supersaas::Appointment>, ...]
 
 #### Get range of appointments
 
@@ -181,6 +191,41 @@ Get range of appointments by `schedule_id`, with `today`, `from` time, `to` time
 
     Supersaas::Client.instance.appointments.range(12345, false, '2018-01-31 00:00:00', '2019-01-31 00:00:00', true) #=> [<Supersaas::Appointment>, ...]/[<Supersaas::Slot>, ...]
 
+#### List Slots
+
+List the slots of a capacity type schedule by `schedule_id`, with optional `start_time`, `finish`, `limit` (default 100, max 2500) and `offset` view params,
+`list(schedule_id, start_time = nil, finish = nil, limit = nil, offset = nil)`:
+
+    Supersaas::Client.instance.slots.list(12345, '2018-01-31 00:00:00', '2019-01-31 00:00:00', 50) #=> [<Supersaas::Slot>, ...]
+
+_Note: slots only work for capacity type schedules. On other schedule types the API returns 405, which raises `Supersaas::Exception` with "Not available for this schedule type"._
+
+#### Get Slot
+
+Get a single slot by `schedule_id` and `slot_id`:
+
+    Supersaas::Client.instance.slots.get(12345, 67890) #=> <Supersaas::Slot>
+
+#### Create Slot
+
+Create a slot with `schedule_id` and slot attributes (`start`, `finish`, `title`, `description`, `location`, `capacity`, `price`, `color`),
+`create(schedule_id, attributes)`. A `capacity` of `'-'` means unlimited, `0` means no places:
+
+    Supersaas::Client.instance.slots.create(12345, {start: '2018-01-31 14:00:00', finish: '2018-01-31 15:00:00', title: 'Yoga', capacity: 10}) #=> http://www.supersaas.com/api/slots/67890.json
+
+#### Update Slot
+
+Update a slot by `schedule_id` and `slot_id` with slot attributes, see the above link,
+`update(schedule_id, slot_id, attributes)`:
+
+    Supersaas::Client.instance.slots.update(12345, 67890, {title: 'Advanced Yoga', capacity: '-'}) #=> {}
+
+#### Delete Slot
+
+Delete a single slot by `schedule_id` and `slot_id`. Bookings on the slot are deleted as well:
+
+    Supersaas::Client.instance.slots.delete(12345, 67890) #=> {}
+
 #### List Template Forms
 
 Get all forms by template `superform_id`, with `from_time`, and `user` params ([see](https://www.supersaas.com/info/dev/form_api)) and `limit`/`offset` pagination params:
@@ -208,16 +253,16 @@ Get a list of promotional coupon codes with pagination parameters `limit` and `o
 
 #### Get a single coupon code
 
-Retrieve information about a single coupon code use with `promotion_code`:
+Retrieve information about a single coupon code by its alphanumeric `promotion_code`:
 
-    Supersaas::Client.instance.promotions.promotion(12345) #=> <Supersaas::Promotion>
+    Supersaas::Client.instance.promotions.promotion('SPRING10') #=> [<Supersaas::Promotion>]
 
 #### Duplicate promotion code
 
 Duplicate a template promotion by giving (new) `promotion_code` and `template_code` in that order,
 `duplicate_promotion_code(promotion_code, template_code)`:
 
-    Supersaas::Client.instance.promotions.duplicate_promotion_code(12345, 94832838) #=> nil
+    Supersaas::Client.instance.promotions.duplicate_promotion_code('SPRING11', 'SPRING10') #=> nil
 
 #### List Groups in an account
 
@@ -235,7 +280,7 @@ Get all account schedules:
 
 Get all services/resources by `schedule_id`:
 
-    Supersaas::Client.instance.schedules.resources(12345) #=> [<Supersaas::Resource>, ...]    
+    Supersaas::Client.instance.schedules.resources(12345) #=> [<Supersaas::Resource>, ...]
 
 _Note: does not work for capacity type schedules._
 
@@ -245,16 +290,40 @@ Get all the available fields of a schedule by `schedule_id`:
 
     Supersaas::Client.instance.schedules.field_list(12345) #=> [<Supersaas::FieldList>, ...]
 
+#### List Input Fields of a Schedule
+
+Get the fields that can be set when creating a booking on a schedule by `schedule_id`, each with a `required` flag:
+
+    Supersaas::Client.instance.schedules.input_field_list(12345) #=> [<Supersaas::FieldList>, ...]
+
+#### Check Credentials
+
+Check that the account name and API key are valid. Returns `true`, or raises `Supersaas::Exception` with status 401:
+
+    Supersaas::Client.instance.ping #=> true
+
+#### Create Webhook
+
+Create a webhook with `target_url`, `event` and `parent_id` ([see](https://www.supersaas.com/info/dev/webhooks)). The event is the trigger letter, e.g. `'U'` new user, `'M'` changed user, `'N'` new appointment, `'C'` changed appointment. The `parent_id` is the schedule id for appointment events, the super form id for form events, and the account id otherwise:
+
+    Supersaas::Client.instance.hooks.create('https://example.com/hook', 'N', 12345) #=> {"id"=>67, "parent_id"=>12345}
+
+#### Delete Webhook
+
+Delete a webhook by `hook_id` and `parent_id`:
+
+    Supersaas::Client.instance.hooks.delete(67, 12345) #=> {}
+
 
 ## Examples
 
 The ./examples folder contains several executable Ruby scripts demonstrating how to use the API Client for common requests.
 
-The examples will require your account name, api key, and some of the examples a schedule id and/or user id and/or form id. These can be set as environment variables. e.g.
+The examples require your account name and API key. The appointments example also needs a schedule id, and optionally takes a user id (otherwise it creates and deletes a user) and a slot id for capacity type schedules. These can be set as environment variables, e.g.
 
     $ gem install supersaas-api-client
-    $ SSS_API_UID=myuserid SSS_API_SCHEDULE=myscheduleid SSS_API_ACCOUNT_NAME=myaccountname SSS_API_KEY=xxxxxxxxxxxxxxxxxxxxxx ./examples/appointments.rb
-    $ SSS_API_FORM=myuserid SSS_API_ACCOUNT_NAME=myaccountname SSS_API_KEY=xxxxxxxxxxxxxxxxxxxxxx ./examples/forms.rb 
+    $ SSS_API_USER=myuserid SSS_API_SCHEDULE=myscheduleid SSS_API_ACCOUNT_NAME=myaccountname SSS_API_KEY=xxxxxxxxxxxxxxxxxxxxxx ./examples/appointments.rb
+    $ SSS_API_ACCOUNT_NAME=myaccountname SSS_API_KEY=xxxxxxxxxxxxxxxxxxxxxx ./examples/forms.rb
     $ SSS_API_ACCOUNT_NAME=myaccountname SSS_API_KEY=xxxxxxxxxxxxxxxxxxxxxx ./examples/users.rb
 
 ## Testing
@@ -265,15 +334,15 @@ The HTTP requests can be stubbed by configuring the client with the `dry_run` op
 
 Note, stubbed requests always return an empty Hash.
 
-The `Client` also provides a `last_request` attribute containing the `Net::HTTP` object from the last performed request, e.g. 
+The `Client` also provides a `last_request` attribute containing the `Net::HTTP` object from the last performed request, e.g.
 
     Supersaas::Client.instance.last_request #=> <Net::HTTP::Get>
 
 The headers, body, path, etc. of the last request can be inspected for assertion in tests, or for troubleshooting failed API requests.
 
-For additional troubleshooting, the client can be configured with the `verbose` option, which will `puts` any JSON contents in the request and response, e.g.
+For additional troubleshooting, the client can be configured with the `verbose` option, which will `puts` any JSON contents in the request and response. Password values in the request are shown as `[FILTERED]`; the request itself is sent unchanged. E.g.
 
-    Supersaas::Client.instance.verbose = true 
+    Supersaas::Client.instance.verbose = true
 
 ## Error Handling
 
@@ -285,10 +354,17 @@ The API Client raises a custom exception for HTTP errors and invalid input. Resc
       # Handle error
     end
 
-Some errors have more information and are printed to the log before raising the error e.g.
+For HTTP errors the exception also carries the status code and the errors the server returned:
+
+    begin
+      Supersaas::Client.instance.slots.get(12345, 999)
+    rescue Supersaas::Exception => e
+      e.message #=> "HTTP Request Error: Not Found"
+      e.status  #=> 404
+      e.errors  #=> [{"status"=>"404", "title"=>"Not found"}]
+    end
 
-    appointment = Supersaas::Client.instance.appointments.create(12345, {bad_field_name: ''})
-    "Error 400, Bad request: unknown attribute 'bad_field_name' for Booking."
+`errors` is an empty array when the response has no JSON error body. `status` is `nil` for errors raised before a request is sent, such as invalid input.
 
 ## Additional Information
 
@@ -298,9 +374,18 @@ Some errors have more information and are printed to the log before raising the
 
 Contact: [support@supersaas.com](mailto:support@supersaas.com)
 
+## Development
+
+The `bin/` scripts are for working on the client itself and are not included in the gem:
+
+    $ bin/setup            # install the development dependencies
+    $ bin/console          # IRB session with the client loaded
+    $ bundle exec rake test
+    $ bundle exec rake lint
+
 ## Releases
 
-The package follows [semantic versioning](https://semver.org/), i.e. MAJOR.MINOR.PATCH 
+The package follows [semantic versioning](https://semver.org/), i.e. MAJOR.MINOR.PATCH.
 
 ## License
 

data/examples/appointments.rb

@@ -26,35 +26,29 @@ else
   return
 end
 
-# give
 user_id = ENV.fetch('SSS_API_USER', nil)
 
 unless user_id
   puts 'User is created and then deleted at the end'
-  params = { full_name: 'Example', name: 'example@example.com', email: 'example@example.com', api_key: 'example' }
+  params = { full_name: 'Example', name: 'example@example.com', email: 'example@example.com' }
   user = Supersaas::Client.instance.users.create(params)
   user_id = user.match(%r{users/(\d+)\.json})[1]
   puts "#New user created #{user_id}"
 end
 
-description = nil
-if user_id
-  description = '1234567890.'
-  params = { full_name: 'Example', description: description, name: 'example@example.com', email: 'example@example.com',
-             mobile: '555-5555', phone: '555-5555', address: 'addr' }
-  if show_slot
-    params[:slot_id] = ENV.fetch('SSS_API_SLOT', nil)
-  else
-    days = rand(1..30)
-    params[:start] = Time.now + (days * 24 * 60 * 60)
-    params[:finish] = params[:start] + (60 * 60)
-  end
-  puts 'creating new appointment...'
-  puts "#### Supersaas::Client.instance.appointments.create(#{schedule_id}, #{user_id}, {...})"
-  Supersaas::Client.instance.appointments.create(schedule_id, user_id, params)
+description = '1234567890.'
+params = { full_name: 'Example', description: description, name: 'example@example.com', email: 'example@example.com',
+           mobile: '555-5555', phone: '555-5555', address: 'addr' }
+if show_slot
+  params[:slot_id] = ENV.fetch('SSS_API_SLOT', nil)
 else
-  puts 'skipping create/update/delete (NO DESTRUCTIVE ACTIONS FOR SCHEDULE DATA)...'
+  days = rand(1..30)
+  params[:start] = Time.now + (days * 24 * 60 * 60)
+  params[:finish] = params[:start] + (60 * 60)
 end
+puts 'creating new appointment...'
+puts "#### Supersaas::Client.instance.appointments.create(#{schedule_id}, #{user_id}, {...})"
+Supersaas::Client.instance.appointments.create(schedule_id, user_id, params)
 
 puts 'listing appointments...'
 puts "#### Supersaas::Client.instance.appointments.list(#{schedule_id}, nil, nil, 25)"
@@ -64,7 +58,7 @@ appointments = Supersaas::Client.instance.appointments.list(schedule_id, nil, ni
 if appointments.size.positive?
   appointment_id = appointments.sample.id
   puts 'getting appointment...'
-  puts "#### Supersaas::Client.instance.appointments.get(#{appointment_id})"
+  puts "#### Supersaas::Client.instance.appointments.get(#{schedule_id}, #{appointment_id})"
   Supersaas::Client.instance.appointments.get(schedule_id, appointment_id)
 end
 
@@ -74,7 +68,7 @@ to = DateTime.now + 360_000
 puts "#### Supersaas::Client.instance.appointments.changes(#{schedule_id},
   '#{from.strftime('%Y-%m-%d %H:%M:%S')}', '#{to.strftime('%Y-%m-%d %H:%M:%S')}', #{show_slot || 'false'})"
 
-Supersaas::Client.instance.appointments.changes(schedule_id, from, show_slot)
+Supersaas::Client.instance.appointments.changes(schedule_id, from, to, show_slot)
 
 puts 'listing available...'
 from = DateTime.now
@@ -100,10 +94,10 @@ appointments.each do |appointment|
   Supersaas::Client.instance.appointments.update(schedule_id, appointment.id, { country: 'FR', address: 'Rue 1' })
 
   puts 'deleting appointment...'
-  puts "#### Supersaas::Client.instance.appointments.delete(#{schedule_id}. #{appointment.id})"
+  puts "#### Supersaas::Client.instance.appointments.delete(#{schedule_id}, #{appointment.id})"
   Supersaas::Client.instance.appointments.delete(schedule_id, appointment.id)
   break
 end
 
-# Puts delete user
+# Delete the user created above
 Supersaas::Client.instance.users.delete(user_id) unless ENV.fetch('SSS_API_USER', nil)

data/examples/forms.rb

@@ -7,7 +7,7 @@ puts '# SuperSaaS Forms Example'
 
 unless Supersaas::Client.instance.account_name && Supersaas::Client.instance.api_key
   puts 'ERROR! Missing account credentials. Rerun the script with your credentials, e.g.'
-  puts '    SSS_API_ACCOUNT_NAME=<myaccountname> SSS_API_KEY=<xxxxxxxxxxxxxxxxxxxxxx> ./examples/appointments.rb'
+  puts '    SSS_API_ACCOUNT_NAME=<myaccountname> SSS_API_KEY=<xxxxxxxxxxxxxxxxxxxxxx> ./examples/forms.rb'
   return
 end
 
@@ -29,9 +29,13 @@ if template_forms.size.positive?
 
   puts 'listing forms from account'
   puts '#### Supersaas::Client.instance.forms.list'
-  form_id = Supersaas::Client.instance.forms.list(template_form_id).sample.id
+  form_id = Supersaas::Client.instance.forms.list(template_form_id).sample&.id
 end
 
-puts 'getting form...'
-puts "#### Supersaas::Client.instance.forms.get(#{form_id})"
-Supersaas::Client.instance.forms.get(form_id)
+if form_id
+  puts 'getting form...'
+  puts "#### Supersaas::Client.instance.forms.get(#{form_id})"
+  Supersaas::Client.instance.forms.get(form_id)
+else
+  puts '... no forms found'
+end

data/examples/groups.rb

@@ -1,3 +1,4 @@
+#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require 'supersaas-api-client'
@@ -6,7 +7,7 @@ puts '# SuperSaaS Groups Example'
 
 unless Supersaas::Client.instance.account_name && Supersaas::Client.instance.api_key
   puts 'ERROR! Missing account credentials. Rerun the script with your credentials, e.g.'
-  puts 'SSS_API_ACCOUNT_NAME=<myaccountname> SSS_API_KEY=<xxxxxxxxxxxxxxxxxxxxxx> ./examples/users.rb'
+  puts 'SSS_API_ACCOUNT_NAME=<myaccountname> SSS_API_KEY=<xxxxxxxxxxxxxxxxxxxxxx> ./examples/groups.rb'
   return
 end
 

data/examples/promotions.rb

@@ -1,3 +1,4 @@
+#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require 'supersaas-api-client'
@@ -6,7 +7,7 @@ puts '# SuperSaaS Promotions Example'
 
 unless Supersaas::Client.instance.account_name && Supersaas::Client.instance.api_key
   puts 'ERROR! Missing account credentials. Rerun the script with your credentials, e.g.'
-  puts 'SSS_API_ACCOUNT_NAME=<myaccountname> SSS_API_KEY=<xxxxxxxxxxxxxxxxxxxxxx> ./examples/users.rb'
+  puts 'SSS_API_ACCOUNT_NAME=<myaccountname> SSS_API_KEY=<xxxxxxxxxxxxxxxxxxxxxx> ./examples/promotions.rb'
   return
 end
 
@@ -19,13 +20,13 @@ puts 'listing promotions...'
 puts '#### Supersaas::Client.instance.promotions.list'
 promotions = Supersaas::Client.instance.promotions.list
 
-[10, promotions.size].min&.times do |i|
+[10, promotions.size].min.times do |i|
   puts 'A promotion'
-  puts "#### Supersaas::Client.instance.promotion(#{promotions[i].id})"
+  puts "#### Supersaas::Client.instance.promotions.promotion('#{promotions[i].code}')"
   Supersaas::Client.instance.promotions.promotion(promotions[i].code)
 end
 
-# Uncomment to try out duplicating a promotional code
+# Uncomment to try out duplicating a promotional code (also uncomment require 'securerandom')
 # puts "duplicate promotional code"
 # puts "#### Supersaas::Client.instance.promotions.duplicate_promotion_code('new_id', 'id_to_duplicate')"
 # Supersaas::Client.instance.promotions.duplicate_promotion_code("pcode#{SecureRandom.hex(4)}", promotions.first.code)

data/examples/schedules.rb

@@ -7,7 +7,7 @@ puts '# SuperSaaS Schedules Example'
 
 unless Supersaas::Client.instance.account_name && Supersaas::Client.instance.api_key
   puts 'ERROR! Missing account credentials. Rerun the script with your credentials, e.g.'
-  puts 'SSS_API_ACCOUNT_NAME=<myaccountname> SSS_API_KEY=<xxxxxxxxxxxxxxxxxxxxxx> ./examples/users.rb'
+  puts 'SSS_API_ACCOUNT_NAME=<myaccountname> SSS_API_KEY=<xxxxxxxxxxxxxxxxxxxxxx> ./examples/schedules.rb'
   return
 end
 
@@ -21,18 +21,18 @@ puts '#### Supersaas::Client.instance.schedules.list'
 schedules = Supersaas::Client.instance.schedules.list
 
 puts 'listing schedule resources...'
-[10, schedules.size].min&.times do |i|
+[10, schedules.size].min.times do |i|
   puts "#### Supersaas::Client.instance.schedules.resources(#{schedules[i].id})"
-  # Capacity schedules bomb
+  # Capacity type schedules have no resources, the API returns an error for them
   begin
     Supersaas::Client.instance.schedules.resources(schedules[i].id)
-  rescue StandardError
-    next
+  rescue Supersaas::Exception => e
+    puts "Skipped: #{e.message}"
   end
 end
 
-puts 'puts listing fields...'
-[10, schedules.size].min&.times do |i|
+puts 'listing fields...'
+[10, schedules.size].min.times do |i|
   puts "#### Supersaas::Client.instance.schedules.field_list(#{schedules[i].id})"
   Supersaas::Client.instance.schedules.field_list(schedules[i].id)
 end

data/examples/slots.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'supersaas-api-client'
+
+puts '# SuperSaaS Slots Example'
+
+unless Supersaas::Client.instance.account_name && Supersaas::Client.instance.api_key
+  puts 'ERROR! Missing account credentials. Rerun the script with your credentials, e.g.'
+  puts 'SSS_API_SCHEDULE=<capacityscheduleid> SSS_API_ACCOUNT_NAME=<myaccountname> SSS_API_KEY=<xxxxxxxxxxxxxxxxxxxxxx> ./examples/slots.rb'
+  return
+end
+
+schedule_id = ENV.fetch('SSS_API_SCHEDULE', nil)
+unless schedule_id
+  puts 'ERROR! Missing capacity type schedule id. Rerun the script with SSS_API_SCHEDULE=<scheduleid>'
+  return
+end
+
+puts "## Account:  #{Supersaas::Client.instance.account_name}"
+puts "## API KEY: #{'*' * Supersaas::Client.instance.api_key.size}"
+
+Supersaas::Client.instance.verbose = true
+
+puts 'creating slot...'
+start = DateTime.now + 1
+finish = start + (1.0 / 24)
+attributes = { start: start.strftime('%Y-%m-%d %H:%M:%S'), finish: finish.strftime('%Y-%m-%d %H:%M:%S'),
+               title: 'Example slot', capacity: 5 }
+puts "#### Supersaas::Client.instance.slots.create(#{schedule_id}, #{attributes})"
+location = Supersaas::Client.instance.slots.create(schedule_id, attributes)
+slot_id = location.to_s[%r{/slots/(\d+)}, 1]
+
+puts 'listing slots...'
+puts "#### Supersaas::Client.instance.slots.list(#{schedule_id})"
+Supersaas::Client.instance.slots.list(schedule_id, nil, nil, 10)
+
+if slot_id
+  puts 'getting, updating and deleting slot...'
+  Supersaas::Client.instance.slots.get(schedule_id, slot_id)
+  Supersaas::Client.instance.slots.update(schedule_id, slot_id, { title: 'Updated example slot', capacity: '-' })
+  Supersaas::Client.instance.slots.delete(schedule_id, slot_id)
+end

data/examples/users.rb

@@ -18,7 +18,7 @@ Supersaas::Client.instance.verbose = true
 
 puts 'creating new user...'
 puts '#### Supersaas::Client.instance.users.create({...})'
-params = { full_name: 'Example', name: 'example@example.com', email: 'example@example.com', api_key: 'example' }
+params = { full_name: 'Example', name: 'example@example.com', email: 'example@example.com' }
 Supersaas::Client.instance.users.create(params)
 new_user_id = nil