supersaas-api-client 1.1.0 → 2.0.0

data/README.md

@@ -1,33 +1,29 @@
 # SuperSaaS Ruby API Client
 
-Online bookings/appointments/calendars in Ruby using the SuperSaaS scheduling platform - https://supersaas.com
+Manage appointments, users, and other object on the [SuperSaaS appointment scheduling](https://www.supersaas.com/) platform in Ruby.
 
-The SuperSaaS API provides services that can be used to add online booking and scheduling functionality to an existing website or CRM software.
+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.
 
 ## Prerequisites
 
 1. [Register for a (free) SuperSaaS account](https://www.supersaas.com/accounts/new), and
-2. get your account name and API key on the [Account Info](https://www.supersaas.com/accounts/edit) page.
+2. Get your account name and API key on the [Account Info](https://www.supersaas.com/accounts/edit) page.
 
-##### Dependencies
+### Dependencies
 
-Ruby 1.9 or greater.
-
-No external libraries. Only the native `json` and `net/http` standard libs are used.
+No external dependencies. Only the `json` and `net/http` gems from the ruby standard library are used.
 
 ## Installation
 
-1: Gemfile
-
-The SuperSaaS Ruby API Client is available from RubyGems and can be included in your project GemFile. Note, 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.
+Install with:
 
-    gem 'supersaas-api-client', '~> 1'
+    $ gem install supersaas-api-client
 
-2: System Gem
+Alternatively, you can use `bundler` to install it by adding this line to you 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.
 
-You can install the SuperSaaS Ruby API Client globally by using the gem command. Open a terminal and enter the following command:
-
-    $ gem install supersaas-api-client
+    gem 'supersaas-api-client', '~> 2'
 
 ## Configuration
 
@@ -67,59 +63,63 @@ Details of the data structures, parameters, and values can be found on the devel
 
 https://www.supersaas.com/info/dev
 
-#### List Schedules
-
-Get all account schedules:
-
-    Supersaas::Client.instance.schedules.list #=> [<Supersaas::Schedule>, ...]
-    
-#### List Resource
-
-Get all services/resources by `schedule_id`:
-
-    Supersaas::Client.instance.schedules.resources(12345) #=> [<Supersaas::Resource>, ...]    
-
-_Note: does not work for capacity type schedules._
-
 #### Create User
 
-Create a user with user attributes params:
+Create a user with user attributes params `create(attributes, user_id = nil, webhook = nil, duplicate = nil)`.
+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.
+Data fields that you can supply can be found [here.](https://www.supersaas.com/info/dev/user_api)
 
-    Supersaas::Client.instance.users.create({full_name: 'Example Name', email: 'example@example.com'}) #=> nil
+    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
 
 #### Update User
 
-Update a user by `user_id` with user attributes params:
+Update a user by `user_id` with user attributes params `update(user_id, attributes, webhook = nil, notfound = nil)`.
+If webhook=true is present it will trigger any webhooks connected to the account.
+To avoid automatically creating a new record, you can add the parameter notfound=error or notfound=ignore to return a 404 Not Found or 200 OK respectively.
+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'}) #=> nil
+    Supersaas::Client.instance.users.update(12345, {full_name: 'New Name'}, true, "ignore") #=> nil
     
 #### Delete User
 
-Delete a single user by `user_id`:
+Delete a single user by `user_id`, and if the user does not exist 404 error will be raised.
 
     Supersaas::Client.instance.users.delete(12345) #=> nil
     
 #### Get User
 
-Get a single user by `user_id`:
+Get a single user by `user_id`, and if the user does not exist 404 error will be raised:
 
     Supersaas::Client.instance.users.get(12345) #=> <Supersaas::User>
 
 #### List Users
 
-Get all users with optional `form` and `limit`/`offset` pagination params:
+Get all users with optional `form` and `limit`/`offset` pagination params, `list(form = nil, limit = nil, offset = nil)`.
+User can have a form attached, and setting `form=true` shows the data:
 
     Supersaas::Client.instance.users.list(false, 25, 0) #=> [<Supersaas::User>, ...]
 
+#### List Fields of User object
+
+Get all the fields available to user object:
+
+    Supersaas::Client.instance.users.field_list #=> [<Supersaas::FieldList>, ...]
+
 #### Create Appointment/Booking
 
-Create an appointment by `schedule_id` and `user_id` with appointment attributes and `form` and `webhook` params:
+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,
+`create(schedule_id, user_id, attributes, form = nil, webhook = nil)`:
 
-    Supersaas::Client.instance.appointments.create(12345, 67890, {full_name: 'Example Name', email: 'example@example.com', slot_id: 12345}, true, true) #=> nil
+    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
 
 #### Update Appointment/Booking
 
-Update an appointment by `schedule_id` and `appointment_id` with appointment attributes params:
+Update an appointment by `schedule_id` and `appointment_id` with appointment attributes, see the above link,
+`update(schedule_id, appointment_id, attributes, form = nil, webhook = nil)`:
 
     Supersaas::Client.instance.appointments.update(12345, 67890, {full_name: 'New Name'}) #=> nil
 
@@ -137,56 +137,113 @@ 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 appointments by `schedule_id`, with `form` and `start_time` and `limit` view params,
+`list(schedule_id, form = nil, start_time = nil, limit = nil)`:
 
     Supersaas::Client.instance.appointments.list(12345, 67890, true, true) #=> [<Supersaas::Appointment>, ...]
 
 #### Get Agenda
 
-Get agenda (upcoming) appointments by `schedule_id` and `user_id`, with `from_time` view param:
+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>, ...]
 
 #### Get Agenda Slots
 
-Get agenda (upcoming) slots by `schedule_id` and `user_id`, with `from_time` view param:
+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>, ...]    
 
-_Note: works only for capacity type schedules._
+_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:
+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>, ...]
 
 #### Get Recent Changes
 
-Get recently changed appointments by `schedule_id`, with `from` time, `to` time and `slot` view param:
+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>, ...]
 
 
 #### Get list of appointments
 
-Get list of appointments by `schedule_id`, with `today`,`from` time, `to` time and `slot` view param:
+Get list of appointments by `schedule_id`, with `today`,`from` time, `to` time and `slot` view params (see [docs](https://www.supersaas.com/info/dev/appointment_api#range)),
+`range(schedule_id, today = false, from_time = nil, to = nil, slot = false, user = nil, resource_id = nil, service_id = nil, limit = nil, offset = nil)`:
 
     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 Forms
 
-#### List Template Forms
-
-Get all forms by template `superform_id`, with `from_time` param:
+Get all forms by template `superform_id`, with `from_time`, and `user` params ([see](https://www.supersaas.com/info/dev/form_api)):
 
     Supersaas::Client.instance.forms.list(12345, '2018-01-31 00:00:00') #=> [<Supersaas::Form>, ...]
 
 #### Get Form
 
-Get a single form by `form_id`:
+Get a single form by `form_id`, will raise 404 error if not found:
 
     Supersaas::Client.instance.forms.get(12345) #=> <Supersaas::Form>
 
+#### Get a list of SuperForms
+
+Get a list of Form templates (SuperForms):
+
+    Supersaas::Client.instance.forms.forms #=> [<Supersaas::SuperForm>, ...]
+
+#### List Promotions
+
+Get a list of promotional coupon codes with paging parameters `limit` and `offset` (see [docs](https://www.supersaas.com/info/dev/promotion_api)),
+`list(template_form_id, from_time = nil, user = nil)`:
+
+    Supersaas::Client.instance.promotions.list #=> [<Supersaas::Promotion>, ...]
+
+#### Get a single coupon code
+
+Retrieve information about a single coupon code use with `promotion_code`:
+
+    Supersaas::Client.instance.promotions.promotion(12345) #=> <Supersaas::Promotion>
+
+#### Duplicate promotion code
+
+Duplicate a template promotion by giving (new) `id` and `template_code` in that order:
+
+    Supersaas::Client.instance.promotions.duplicate_promotion_code(12345) #=> nil
+
+#### List Groups in an account
+
+List Groups in an account ([see](https://www.supersaas.com/info/dev/information_api)):
+
+    Supersaas::Client.instance.groups.list #=> [<Supersaas::Group>, ...]
+
+#### List Schedules
+
+Get all account schedules:
+
+    Supersaas::Client.instance.schedules.list #=> [<Supersaas::Schedule>, ...]
+
+#### List Services / Resources
+
+Get all services/resources by `schedule_id`:
+
+    Supersaas::Client.instance.schedules.resources(12345) #=> [<Supersaas::Resource>, ...]    
+
+_Note: does not work for capacity type schedules._
+
+#### List Fields of a Schedule
+
+Get all the available fields of a schedule by `schedule_id`:
+
+    Supersaas::Client.instance.schedules.field_list(12345) #=> [<Supersaas::FieldList>, ...]
+
+
 ## Examples
 
 The ./examples folder contains several executable Ruby scripts demonstrating how to use the API Client for common requests.
@@ -226,22 +283,16 @@ The API Client raises a custom exception for HTTP errors and invalid input. Resc
       # Handle error
     end
 
-Validation errors are assigned to the response model. e.g.
+Some errors have more information and are printed to the log before raising the error e.g.
 
     appointment = Supersaas::Client.instance.appointments.create(12345, {bad_field_name: ''})
-    appointment.errors #=> [{"status":"400","title":"Bad request: unknown attribute 'bad_field_name' for Booking."}]
+    "Error 400, Bad request: unknown attribute 'bad_field_name' for Booking."
 
 ## Additional Information
 
 + [SuperSaaS Registration](https://www.supersaas.com/accounts/new)
 + [Product Documentation](https://www.supersaas.com/info/support)
 + [Developer Documentation](https://www.supersaas.com/info/dev)
-+ [Python API Client](https://github.com/SuperSaaS/supersaas-python-api-client)
-+ [PHP API Client](https://github.com/SuperSaaS/supersaas-php-api-client)
-+ [NodeJS API Client](https://github.com/SuperSaaS/supersaas-nodejs-api-client)
-+ [C# API Client](https://github.com/SuperSaaS/supersaas-csharp-api-client)
-+ [Objective-C API Client](https://github.com/SuperSaaS/supersaas-objc-api-client)
-+ [Go API Client](https://github.com/SuperSaaS/supersaas-go-api-client)
 
 Contact: [support@supersaas.com](mailto:support@supersaas.com)
 

data/Rakefile

@@ -1,10 +1,12 @@
-require "bundler/gem_tasks"
-require "rake/testtask"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
 end
 
-task :default => :test
+task default: :test

data/bin/console

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "bundler/setup"
-require "supersaas-api-client"
+require 'bundler/setup'
+require 'supersaas-api-client'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +11,5 @@ require "supersaas-api-client"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start(__FILE__)

data/examples/appointments.rb

@@ -1,19 +1,19 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "date"
-require "pp"
-require "supersaas-api-client"
+require 'date'
+require 'supersaas-api-client'
 
-puts "\n\r# SuperSaaS Appointments Example\n\r"
+puts "# SuperSaaS Appointments 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.\n\r"
-  puts "    SSS_API_ACCOUNT_NAME=<myaccountname> SSS_API_KEY=<api_key> ./examples/appointments.rb\n\r"
+  puts "ERROR! Missing account credentials. Rerun the script with your credentials, e.g."
+  puts "SSS_API_ACCOUNT_NAME=<myaccountname> SSS_API_KEY=<api_key> ./examples/appointments.rb"
   return
 end
 
 puts "## Account:  #{Supersaas::Client.instance.account_name}"
-puts "## API Key: #{'*' * Supersaas::Client.instance.api_key.size}\n\r"
+puts "## API Key: #{'*' * Supersaas::Client.instance.api_key.size}"
 
 Supersaas::Client.instance.verbose = true
 
@@ -21,64 +21,92 @@ if ENV['SSS_API_SCHEDULE']
   schedule_id = ENV['SSS_API_SCHEDULE']
   show_slot = ENV['SSS_API_SLOT'] ? true : false
 else
-  puts "ERROR! Missing schedule id. Rerun the script with your schedule id, e.g.\n\r"
-  puts "    SSS_API_SCHEDULE=<scheduleid> ./examples/appointments.rb\n\r"
+  puts "ERROR! Missing schedule id. Rerun the script with your schedule id, e.g."
+  puts "    SSS_API_SCHEDULE=<scheduleid> ./examples/appointments.rb"
   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' }
+  user = Supersaas::Client.instance.users.create(params)
+  user_id = user.match(/users\/(\d+)\.json/)[1]
+  puts "#New user created #{user_id}"
+end
+
+
 description = nil
-new_appointment_id = nil
-user = ENV['SSS_API_USER']
-if user
+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'}
+  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['SSS_API_SLOT']
+    params[:slot_id] = ENV.fetch('SSS_API_SLOT', nil)
   else
-    days = 1 + rand(30)
+    days = rand(1..30)
     params[:start] = Time.now + (days * 24 * 60 * 60)
     params[:finish] = params[:start] + (60 * 60)
   end
-  puts "\n\rcreating new appointment..."
-  puts "\n\r#### Supersaas::Client.instance.appointments.create(#{schedule_id}, #{user}, {...})\n\r"
-  Supersaas::Client.instance.appointments.create(schedule_id, user, params)
+  puts "creating new appointment..."
+  puts "#### Supersaas::Client.instance.appointments.create(#{schedule_id}, #{user_id}, {...})"
+  Supersaas::Client.instance.appointments.create(schedule_id, user_id, params)
 else
-  puts "\n\rskipping create/update/delete (NO DESTRUCTIVE ACTIONS FOR SCHEDULE DATA)...\n\r"
+  puts "skipping create/update/delete (NO DESTRUCTIVE ACTIONS FOR SCHEDULE DATA)..."
 end
 
-puts "\n\rlisting appointments..."
-puts "\n\r#### Supersaas::Client.instance.appointments.list(#{schedule_id}, nil, nil, 25)\n\r"
+puts "listing appointments..."
+puts "#### Supersaas::Client.instance.appointments.list(#{schedule_id}, nil, nil, 25)"
 
 appointments = Supersaas::Client.instance.appointments.list(schedule_id, nil, nil, 25)
-appointments.each do |appointment|
-  puts "#{description} == #{appointment.description}"
-  if description == appointment.description
-    puts "\n\rupdating appointment..."
-    puts "\n\r#### Supersaas::Client.instance.appointments.update(#{schedule_id}, #{new_appointment_id}, {...})\n\r"
-    Supersaas::Client.instance.appointments.update(schedule_id, new_appointment_id, {country: 'FR', address: 'Rue 1'})
-
-    puts "\n\rdeleting appointment..."
-    puts "\n\r#### Supersaas::Client.instance.appointments.delete(#{schedule_id}. #{new_appointment_id})\n\r"
-    Supersaas::Client.instance.appointments.delete(schedule_id, new_appointment_id)
-    break
-  end
-end
 
-if appointments.size > 0
+if appointments.size.positive?
   appointment_id = appointments.sample.id
-  puts "\n\rgetting appointment..."
-  puts "\n\r#### Supersaas::Client.instance.appointments.get(#{appointment_id})\n\r"
+  puts "getting appointment..."
+  puts "#### Supersaas::Client.instance.appointments.get(#{appointment_id})"
   Supersaas::Client.instance.appointments.get(schedule_id, appointment_id)
 end
 
-puts "\n\rlisting changes..."
+puts "listing changes..."
 from = DateTime.now - 120
-puts "\n\r#### 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'})\n\r"
+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)
 
-puts "\n\rlisting available..."
+puts "listing available..."
 from = DateTime.now
-puts "\n\r#### Supersaas::Client.instance.appointments.available(#{schedule_id}, '#{from.strftime("%Y-%m-%d %H:%M:%S")}')\n\r"
+puts "#### Supersaas::Client.instance.appointments.available(#{schedule_id},
+  '#{from.strftime('%Y-%m-%d %H:%M:%S')}')"
+
+Supersaas::Client.instance.appointments.available(schedule_id, from)
+
+puts "Appointments for a single user..."
+user = Supersaas::Client.instance.users.list(nil, 1).first
+from = DateTime.now
+puts "#### Supersaas::Client.instance.appointments.agenda(#{schedule_id}, user.id,
+  '#{from.strftime('%Y-%m-%d %H:%M:%S')}')"
+Supersaas::Client.instance.appointments.agenda(schedule_id, user.id, from.strftime('%Y-%m-%d %H:%M:%S'))
+
+# Update and delete appointments
+appointments.each do |appointment|
+  puts "#{description} == #{appointment.description}"
+  next unless description == appointment.description
+
+  puts "updating appointment..."
+  puts "#### Supersaas::Client.instance.appointments.update(#{schedule_id}, #{appointment.id}, {...})"
+  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})"
+  Supersaas::Client.instance.appointments.delete(schedule_id, appointment.id)
+  break
+end
 
-Supersaas::Client.instance.appointments.available(schedule_id, from)
+# Puts delete user
+unless ENV.fetch('SSS_API_USER', nil)
+  Supersaas::Client.instance.users.delete(user_id)
+end

data/examples/forms.rb

@@ -1,39 +1,37 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "pp"
-require "supersaas-api-client"
+require 'supersaas-api-client'
 
-puts "\n\r# SuperSaaS Forms Example\n\r"
+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.\n\r"
-  puts "    SSS_API_ACCOUNT_NAME=<myaccountname> SSS_API_KEY=<xxxxxxxxxxxxxxxxxxxxxx> ./examples/appointments.rb\n\r"
+  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"
   return
 end
 
 puts "## Account:  #{Supersaas::Client.instance.account_name}"
-puts "## API Key: #{'*' * Supersaas::Client.instance.api_key.size}\n\r"
+puts "## API Key: #{'*' * Supersaas::Client.instance.api_key.size}"
 
 Supersaas::Client.instance.verbose = true
 
-if ENV['SSS_API_FORM']
-  form_id = ENV['SSS_API_FORM']
-else
-  puts "ERROR! Missing form id. Rerun the script with your form id, e.g.\n\r"
-  puts "    SSS_API_FORM=<formid> ./examples/forms.rb\n\r"
-  return
-end
+puts "You will need to create a form, and also attach the form to a booking, see documentation on how to do that"
+puts "The below example will take a form in random, and if it is not attached to something then 404 error will be raised"
+
+puts "listing forms..."
+puts "#### Supersaas::Client.instance.forms.forms"
 
-puts "\n\rlisting forms..."
-puts "\n\r#### Supersaas::Client.instance.forms.list(#{form_id})\n\r"
+template_forms = Supersaas::Client.instance.forms.forms
 
-forms = Supersaas::Client.instance.forms.list(form_id)
+if template_forms.size.positive?
+  template_form_id = template_forms.sample.id
 
-if forms.size > 0
-  form_id = forms.sample.id
-  puts "\n\rgetting form..."
-  puts "\n\r#### Supersaas::Client.instance.forms.get(#{form_id})\n\r"
-  form = Supersaas::Client.instance.forms.get(form_id)
+  puts "listing forms from account"
+  puts "#### Supersaas::Client.instance.forms.list"
+  form_id = Supersaas::Client.instance.forms.list(template_form_id).sample.id
 end
 
-puts
+puts "getting form..."
+puts "#### Supersaas::Client.instance.forms.get(#{form_id})"
+Supersaas::Client.instance.forms.get(form_id)

data/examples/groups.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'supersaas-api-client'
+
+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"
+  return
+end
+
+puts "## Account:  #{Supersaas::Client.instance.account_name}"
+puts "## API KEY: #{'*' * Supersaas::Client.instance.api_key.size}"
+
+Supersaas::Client.instance.verbose = true
+
+puts "listing groups..."
+puts "#### Supersaas::Client.instance.groups.list"
+Supersaas::Client.instance.groups.list

data/examples/promotions.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'supersaas-api-client'
+
+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"
+  return
+end
+
+puts "## Account:  #{Supersaas::Client.instance.account_name}"
+puts "## API KEY: #{'*' * Supersaas::Client.instance.api_key.size}"
+
+Supersaas::Client.instance.verbose = true
+
+puts "listing promotions..."
+puts "#### Supersaas::Client.instance.promotions.list"
+promotions = Supersaas::Client.instance.promotions.list
+
+[10, promotions.size].min&.times do |i|
+  puts "A promotion"
+  puts "#### Supersaas::Client.instance.promotion(#{promotions[i].id})"
+  Supersaas::Client.instance.promotions.promotion(promotions[i].code)
+end
+
+# Uncomment to try out duplicating a promotional code
+# 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)
+# puts

data/examples/schedules.rb

@@ -1,27 +1,39 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "supersaas-api-client"
+require 'supersaas-api-client'
 
-puts "\n\r# SuperSaaS Schedules Example\n\r"
+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.\n\r"
-  puts "    SSS_API_ACCOUNT_NAME=<myaccountname> SSS_API_KEY=<xxxxxxxxxxxxxxxxxxxxxx> ./examples/users.rb\n\r"
+  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"
   return
 end
 
 puts "## Account:  #{Supersaas::Client.instance.account_name}"
-puts "## API KEY: #{'*' * Supersaas::Client.instance.api_key.size}\n\r"
+puts "## API KEY: #{'*' * Supersaas::Client.instance.api_key.size}"
 
 Supersaas::Client.instance.verbose = true
 
-puts "\n\rlisting schedules..."
-puts "\n\r#### Supersaas::Client.instance.schedules.list\n\r"
+puts "listing schedules..."
+puts "#### Supersaas::Client.instance.schedules.list"
 schedules = Supersaas::Client.instance.schedules.list
 
-puts "\n\rlisting schedule resources..."
-[10, schedules.size].min.times do |i|
-  puts "\n\r#### Supersaas::Client.instance.schedules.resources(#{schedules[i].id})\n\r"
+puts "listing schedule resources..."
+[10, schedules.size].min&.times do |i|
+  puts "#### Supersaas::Client.instance.schedules.resources(#{schedules[i].id})"
+  # Capacity schedules bomb
+  begin
   Supersaas::Client.instance.schedules.resources(schedules[i].id)
+  rescue
+    next
+  end
 end
-puts
+
+puts "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
+puts