supersaas-api-client 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2de956c3f1649c9bfbee7b31f966400071895afbdf1815a488c8fa99d2f32d61
+  data.tar.gz: 4184f2dd95b283d588ef1465d5ee18aa9b3ae393e90805badc196168218a8f09
+SHA512:
+  metadata.gz: 5a71ff165dc07cddaccb615b8f55264d8091fa125336da21d1fba902e16d630f48cdb3f30f35873bb923d7c6b10fb673733b4c8f1d5a44e500eb6d92fb7cdd3e
+  data.tar.gz: 3f48e1883d801d77badc577c785efb09a1b43e13b05b0fd94b8956de44d3ed9bb0d5448ff74fba1845372b390209d9d8aa0a44163377e0dacf784494724cc55d

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.DS_Store
+.idea/*
+*.gem

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+gemspec

data/Gemfile.lock

@@ -0,0 +1,22 @@
+PATH
+  remote: .
+  specs:
+    supersaas-api-client (0.9.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    minitest (5.11.3)
+    rake (10.5.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.16)
+  minitest (~> 5.0)
+  rake (~> 10.0)
+  supersaas-api-client!
+
+BUNDLED WITH
+   1.16.1

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 SuperSaaS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,252 @@
+# SuperSaaS Ruby API Client
+
+Online bookings/appointments/calendars in Ruby using the SuperSaaS scheduling platform - https://supersaas.com
+
+The SuperSaaS API provides services that can be used to add online booking and scheduling functionality to an existing website or CRM software.
+
+## Prerequisites
+
+1. [Register for a (free) SuperSaaS account](https://www.supersaas.com/accounts/new), and
+2. get your account name and password.
+
+##### Dependencies
+
+Ruby 1.9 or greater.
+
+No external libraries. Only the native `json` and `net/http` standard libs 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.
+
+    gem 'supersaas-api-client', '~> 1'
+
+2: System Gem
+
+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
+
+## 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:
+
+    Supersaas::Client.configure do |config|
+      config.account_name = 'accnt'
+      config.password = 'pwd'
+    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 password.
+
+    ENV['SSS_API_ACCOUNT_NAME'] = 'your-env-supersaas-account-name'
+    ENV['SSS_API_PASSWORD'] = 'your-env-supersaas-account-name' 
+    Supersaas::Client.instance.account_name #=> 'your-env-supersaas-account-name'
+    Supersaas::Client.instance.password #=> 'your-env-supersaas-account-name'
+    
+All configuration options can be individually set on the client.
+
+    Supersaas::Client.instance.password = 'pwd' 
+    Supersaas::Client.instance.verbose = true
+    ...
+
+## API Methods
+
+Details of the data structures, parameters, and values can be found on the developer documentation site:
+
+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:
+
+    Supersaas::Client.instance.users.create({full_name: 'Example Name', email: 'example@example.com'}) #=> nil
+
+#### Update User
+
+Update a user by `user_id` with user attributes params:
+
+    Supersaas::Client.instance.users.update(12345, {full_name: 'New Name'}) #=> nil
+    
+#### Delete User
+
+Delete a single user by `user_id`:
+
+    Supersaas::Client.instance.users.delete(12345) #=> nil
+    
+#### Get User
+
+Get a single user by `user_id`:
+
+    Supersaas::Client.instance.users.get(12345) #=> <Supersaas::User>
+
+#### List Users
+
+Get all users with optional `form` and `limit`/`offset` pagination params:
+
+    Supersaas::Client.instance.users.list(false, 25, 0) #=> [<Supersaas::User>, ...]
+
+#### Create Appointment/Booking
+
+Create an appointment by `schedule_id` and `user_id` with appointment attributes and `form` and `webhook` params:
+
+    Supersaas::Client.instance.appointments.create(12345, 67890, {full_name: 'Example Name', email: 'example@example.com', slot_id: 12345}, true, true) #=> nil
+
+#### Update Appointment/Booking
+
+Update an appointment by `schedule_id` and `appointment_id` with appointment attributes params:
+
+    Supersaas::Client.instance.appointments.update(12345, 67890, {full_name: 'New Name'}) #=> nil
+
+#### Delete Appointment/Booking
+
+Delete a single appointment by `appointment_id`:
+
+    Supersaas::Client.instance.appointments.delete(12345) #=> nil
+
+#### Get Appointment/Booking
+
+Get a single appointment by `schedule_id` and `appointment_id`:
+
+    Supersaas::Client.instance.appointments.get(12345, 67890) #=> <Supersaas::Appointment>
+
+#### List Appointments/Bookings
+
+List appointments by `schedule_id`, with `form` and `start_time` and `limit` view params:
+
+    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:
+
+    Supersaas::Client.instance.appointments.agenda(12345, 67890, '2018-1-31 00:00:00') #=> [<Supersaas::Appointment>, ...]
+
+#### Get Agenda Slots
+
+Get agenda (upcoming) slots by `schedule_id` and `user_id`, with `from_time` view param:
+
+    Supersaas::Client.instance.appointments.agenda_slots(12345, 67890, '2018-1-31 00:00:00') #=> [<Supersaas::Slot>, ...]    
+
+_Note: works only for capacity type schedules._
+
+#### Get Available Appointments/Bookings
+
+Get available appointments by `schedule_id`, with `from` time and `length_minutes` and `resource` params:
+
+    Supersaas::Client.instance.appointments.available(12345, '2018-1-31 00:00:00', 15, 'My Class') #=> [<Supersaas::Appointment>, ...]
+
+#### Get Recent Changes
+
+Get recently changed appointments by `schedule_id`, with `from_time` view param:
+
+    Supersaas::Client.instance.appointments.changes(12345, '2018-1-31 00:00:00', true) #=> [<Supersaas::Appointment>, ...]
+
+#### Get Recent Changes Slots
+
+Get recently changed slots by `schedule_id`, with `from_time` view param:
+
+    Supersaas::Client.instance.appointments.changes_slots(12345, '2018-1-31 00:00:00', true) #=> [<Supersaas::Slot>, ...]
+
+#### List Template Forms
+
+Get all forms by template `superform_id`, with `from_time` param:
+
+    Supersaas::Client.instance.forms.list(12345, '2018-1-31 00:00:00') #=> [<Supersaas::Form>, ...]
+
+#### Get Form
+
+Get a single form by `form_id`:
+
+    Supersaas::Client.instance.forms.get(12345) #=> <Supersaas::Form>
+
+## 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, password, 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.
+
+    $ gem install supersaas-api-client
+    $ SSS_API_UID=myuserid SSS_API_SCHEDULE=myscheduleid SSS_API_ACCOUNT_NAME=myaccountname SSS_API_PASSWORD=mypassword ./examples/appointments.rb
+    $ SSS_API_FORM=myuserid SSS_API_ACCOUNT_NAME=myaccountname SSS_API_PASSWORD=mypassword ./examples/forms.rb 
+    $ SSS_API_ACCOUNT_NAME=myaccountname SSS_API_PASSWORD=mypassword ./examples/users.rb
+
+## Testing
+
+The HTTP requests can be stubbed by configuring the client with the `dry_run` option, e.g.
+
+    Supersaas::Client.instance.dry_run = true
+
+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. 
+
+    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.
+
+    Supersaas::Client.instance.verbose = true 
+
+## Error Handling
+
+The API Client raises a custom exception for HTTP errors and invalid input. Rescue from `Supersaas::Exception` when making API requests. e.g.
+
+    begin
+      Supersaas::Client.instance.users.get
+    rescue Supersaas::Exception => e
+      # Handle error
+    end
+
+Validation errors are assigned to the response model. 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."}]
+
+## 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)
+
+## Releases
+
+The package follows [semantic versioning](https://semver.org/), i.e. MAJOR.MINOR.PATCH 
+
+## License
+
+The SuperSaaS Ruby API Client is available under the MIT license. See the LICENSE file for more info.

data/Rakefile

@@ -0,0 +1,10 @@
+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"]
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+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.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/examples/appointments.rb

@@ -0,0 +1,84 @@
+#!/usr/bin/env ruby
+
+require "date"
+require "pp"
+require "supersaas-api-client"
+
+puts "\n\r# SuperSaaS Appointments Example\n\r"
+
+unless Supersaas::Client.instance.account_name && Supersaas::Client.instance.password
+  puts "ERROR! Missing account credentials. Rerun the script with your credentials, e.g.\n\r"
+  puts "    SSS_API_ACCOUNT_NAME=<myaccountname> SSS_API_PASSWORD=<mypassword> ./examples/appointments.rb\n\r"
+  return
+end
+
+puts "## Account:  #{Supersaas::Client.instance.account_name}"
+puts "## Password: #{'*' * Supersaas::Client.instance.password.size}\n\r"
+
+Supersaas::Client.instance.verbose = true
+
+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"
+  return
+end
+
+description = nil
+new_appointment_id = nil
+user = ENV['SSS_API_USER']
+if user
+  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['SSS_API_SLOT']
+  else
+    days = 1 + rand(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)
+else
+  puts "\n\rskipping create/update/delete (NO DESTRUCTIVE ACTIONS FOR SCHEDULE DATA)...\n\r"
+end
+
+puts "\n\rlisting appointments..."
+puts "\n\r#### Supersaas::Client.instance.appointments.list(#{schedule_id}, nil, nil, 25)\n\r"
+
+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(#{new_appointment_id})\n\r"
+    Supersaas::Client.instance.appointments.delete(new_appointment_id)
+    break
+  end
+end
+
+if appointments.size > 0
+  appointment_id = appointments.sample.id
+  puts "\n\rgetting appointment..."
+  puts "\n\r#### Supersaas::Client.instance.appointments.get(#{appointment_id})\n\r"
+  Supersaas::Client.instance.appointments.get(schedule_id, appointment_id)
+end
+
+puts "\n\rlisting changes..."
+from = DateTime.now - 120
+puts "\n\r#### Supersaas::Client.instance.appointments.changes(#{schedule_id}, '#{from.strftime("%Y-%m-%d %H:%M:%S")}', #{show_slot || 'false'})\n\r"
+
+Supersaas::Client.instance.appointments.changes(schedule_id, from, show_slot)
+
+puts "\n\rlisting available..."
+from = DateTime.now
+puts "\n\r#### Supersaas::Client.instance.appointments.available(#{schedule_id}, '#{from.strftime("%Y-%m-%d %H:%M:%S")}')\n\r"
+
+Supersaas::Client.instance.appointments.available(schedule_id, from)

data/examples/forms.rb

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+
+require "pp"
+require "supersaas-api-client"
+
+puts "\n\r# SuperSaaS Forms Example\n\r"
+
+unless Supersaas::Client.instance.account_name && Supersaas::Client.instance.password
+  puts "ERROR! Missing account credentials. Rerun the script with your credentials, e.g.\n\r"
+  puts "    SSS_API_ACCOUNT_NAME=<myaccountname> SSS_API_PASSWORD=<mypassword> ./examples/appointments.rb\n\r"
+  return
+end
+
+puts "## Account:  #{Supersaas::Client.instance.account_name}"
+puts "## Password: #{'*' * Supersaas::Client.instance.password.size}\n\r"
+
+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 "\n\rlisting forms..."
+puts "\n\r#### Supersaas::Client.instance.forms.list(#{form_id})\n\r"
+
+forms = Supersaas::Client.instance.forms.list(form_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)
+end
+
+puts

data/examples/schedules.rb

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+
+require "supersaas-api-client"
+
+puts "\n\r# SuperSaaS Schedules Example\n\r"
+
+unless Supersaas::Client.instance.account_name && Supersaas::Client.instance.password
+  puts "ERROR! Missing account credentials. Rerun the script with your credentials, e.g.\n\r"
+  puts "    SSS_API_ACCOUNT_NAME=<myaccountname> SSS_API_PASSWORD=<mypassword> ./examples/users.rb\n\r"
+  return
+end
+
+puts "## Account:  #{Supersaas::Client.instance.account_name}"
+puts "## Password: #{'*' * Supersaas::Client.instance.password.size}\n\r"
+
+Supersaas::Client.instance.verbose = true
+
+puts "\n\rlisting schedules..."
+puts "\n\r#### Supersaas::Client.instance.schedules.list\n\r"
+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"
+  Supersaas::Client.instance.schedules.resources(schedules[i].id)
+end
+puts

data/examples/users.rb

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+
+require "supersaas-api-client"
+
+puts "\n\r# SuperSaaS Users Example\n\r"
+
+unless Supersaas::Client.instance.account_name && Supersaas::Client.instance.password
+  puts "ERROR! Missing account credentials. Rerun the script with your credentials, e.g.\n\r"
+  puts "    SSS_API_ACCOUNT_NAME=<myaccountname> SSS_API_PASSWORD=<mypassword> ./examples/users.rb\n\r"
+  return
+end
+
+puts "## Account:  #{Supersaas::Client.instance.account_name}"
+puts "## Password: #{'*' * Supersaas::Client.instance.password.size}\n\r"
+
+Supersaas::Client.instance.verbose = true
+
+puts "creating new user..."
+puts "\n\r#### Supersaas::Client.instance.users.create({...})\n\r"
+params = {full_name: 'Example', name: 'example@example.com', email: 'example@example.com', password: 'example'}
+Supersaas::Client.instance.users.create(params)
+new_user_id = nil
+
+puts "\n\rlisting users..."
+puts "\n\r#### Supersaas::Client.instance.users.list(nil, 50)\n\r"
+
+users = Supersaas::Client.instance.users.list(nil, 50)
+users.each do |user|
+  new_user_id = user.id if user.name == params[:email] || user.email == params[:email]
+end
+
+if new_user_id
+  puts "\n\rgetting user..."
+  puts "\n\r#### Supersaas::Client.instance.users.get(#{new_user_id})\n\r"
+  user = Supersaas::Client.instance.users.get(new_user_id)
+
+  puts "\n\rupdating user..."
+  puts "\n\r#### Supersaas::Client.instance.users.update(#{new_user_id})\n\r"
+  Supersaas::Client.instance.users.update(new_user_id, {country: 'FR', address: 'Rue 1'})
+
+  puts "\n\rdeleting user..."
+  puts "\n\r#### Supersaas::Client.instance.users.delete(#{user.id})\n\r"
+  Supersaas::Client.instance.users.delete(user.id)
+else
+  puts "\n\r... did not find user in list"
+end
+
+puts "\n\rcreating user with errors..."
+puts "\n\r#### Supersaas::Client.instance.users.create\n\r"
+Supersaas::Client.instance.users.create({name: 'error'})
+puts