antaeus-sdk 0.2.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 250a4b2c9a9e103be45ae8f6d28029664db8d8fa
+  data.tar.gz: b1aa610aa33a51ec61f79feee4831bb348438558
+SHA512:
+  metadata.gz: f3147a11ca8e7b7c3908151b7d2ffcb7799d287c8d79d5cfee7c5c50b06a7fe52c1a975e994eb3739675b20555a5e8b1067ba5e2a1ee6d63a16dece482ea3a68
+  data.tar.gz: ea5ff1f4fbfe17642390ea2394267d2ebcaf3554f0d625fbcac6e5b473bfa326bb02bbaee46b2c4c3c71ad990d2dc816f5800c590ae1bd8aa3bb6f960c7d1ad3

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2016 KnuEdge
+
+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,119 @@
+The Antaeus SDK for Ruby
+====================
+
+About
+----
+Antaeus is a guest management system written by [KnuEdge](https://www.knuedge.com). The name comes from [a figure in Greek mythology](https://en.wikipedia.org/wiki/Antaeus) that would challenge travellers passing through his land to compete with him in a wrestling match. While this application has little to do with wrestling, it is used to track passers-by at [KnuEdge](https://www.knuedge.com) office locations.
+
+This is the Ruby SDK designed to aid in and serve as a reference for interacting with the [Antaeus API](#). This SDK is certainly not required to use the API (everything could be done with `curl` calls or most any REST client), but it provides first-class Ruby objects to make things easy for a Ruby developer. It also happens to serve as the basis for the [Antaeus Web](#) application.
+
+Building and Installing
+----
+Building the gem requires a modern Ruby:
+
+    # highly recommend using RVM here, and Ruby 2.x or above
+    gem build antaeus-sdk.gemspec
+    # install what you just built
+    gem install antaeus-sdk-*.gem
+
+That said, recent releases should be available on [rubygems.org](https://rubygems.org/) so building is probably not necessary.
+
+Just add the following to your Gemfile:
+
+    gem 'antaeus-sdk', '~> 0.2'
+
+Then run:
+
+    bundle install
+
+If you're not using [bundler](http://bundler.io/) for some reason (shame on you!), you can manually install like so:
+
+    gem install antaeus-sdk
+
+If you see a message like this:
+
+    Thanks for installing the Antaeus Ruby SDK!
+
+You should be all set!
+
+Usage
+------
+Check back, because this file will be updated with a lot more usage examples.
+
+For simplicity, this gem includes a CLI application for interacting with an API backend. To use it, run:
+
+    $ antaeus-cli
+
+It should be in your `PATH`. On the first run, it will create a directory called `~/.antaeus` (meaning it places it in your home directory), and it will drop a base configuration for the tool at `~/.antaeus/client.yml`. Edit this file, specifically changing `base_url`, `login`, and `password` as required. This document will be updated to show all configuration options available, along with their default values, in the future.
+
+The CLI tool really is just a shortcut to the next few lines of boilerplate code to connect to the backend API and reuse configuration from a config file.
+
+For a typical custom ruby application, you'll need to do something like the following to get started:
+
+    require 'antaeus-sdk'
+    
+    # create an 'instance' of the User API Client Singleton
+    client = Antaeus::UserAPIClient.instance
+    # authenticate
+    client.authenticate 'username', 'password'
+
+From here, whether using the provided CLI tool or building a custom application, the instructions are the same.
+
+First, connect the client to the API backend and obtain an API token:
+
+    client.connect
+
+You'll probably see something similar to the following:
+
+    => #<RestClient::Resource:0x007fa693ecbbe8
+     @block=nil,
+     @options=
+      {:content_type=>:json,
+       :accept=>:json,
+       :headers=>{:"X-API-Token:"=>"cv0qTNvJsTRMEn2jzLBvb+T25l6zc8feG3s62Q6XDPbB9isxG3gJ1wxRpyxINHgPRd9lu+afLrIzFj50KjLIFtPkGc5bOJKyO7BCCWFGY0erhbhFpXLJZg=="}},
+     @url="https://antaeus.example.com">
+
+This API client is built to be very flexible, working for both guest users (using the `GuestAPIClient`), typical users (using the `UserAPIClient` shown in this example), as well as for trusted front-end applications (using the same `UserAPIClient` in multi-user / impersonation mode). For this reason, Antaeus resources (subclasses of the `Antaeus::Resource` class) need to know which client to use to perform a given operation on the backend API. These resources are smart enough to keep using the same client, but a client (a sublcass of the `Antaeus::APIClient` class) must be provided to all class methods. For instance:
+
+    # Retrieve a list of all Guests known to the system
+    guests = Antaeus::Resources::Guest.all(client: client)
+
+Note though, that any objects created using a class method with a client provided carry along that same client. This means that method chaining (for instance, on resource collections) is simple:
+
+    # For simplicity, include the Antaeus::Resources module / namespace
+    include Antaeus::Resources
+    
+    # Retrieve all guests with "gmail.com" in their email address
+    guests = Guest.all(client: client).where(:email, /gmail\.com/, comparison: :match)
+    # Or
+    all_guests = Guest.all(client: client)
+    guests = all_guests.where(:email, /gmail\.com/, comparison: :match)
+    # Or even
+    guests = Guest.where(:email, /gmail\.com/, comparison: :match, client: client)
+
+The `#where()` is an instance method on the `Antaeus::ResourceCollection` class, which means that the searching is actually done locally. For small installations of Antaeus (or especially powerful client machines), this is likely the fastest way to do searching. That said, `Antaeus::Resource` also provides a `.search()` method that submits queries to the server for processing, returning only matching resources. This style of searching is less flexible, and may be slower for some operations given the lazy-loading of resource model data employed by this SDK.
+
+The following resource classes (all under the `Antaeus::Resources` namespace) are available for typical API operations:
+
+* `Appointment`
+  * Used for creating, listing, and managing guest appointments
+* `Group`
+  * Read-only, used for listing and querying backend groups and their members. Only available to administrators and via the `UserAPIClient`
+* `Guest`
+  * Used for creating, listing, and managing guests.
+* `Hook`
+  * Used to configure plugins, targeting certain plugins at named system events. Only available to administrators and via the `UserAPIClient`
+* `Location`
+  * Used for creating, listing, and managing office locations. Read-only to non-administrators.
+* `RemoteApplication`
+  * Used for creating, listing, and managing remote front-end applications to the API. This is for very advanced cases only (such as integrating with different authentication systems). Only available to administrators and via the `UserAPIClient`
+* `User`
+  * Read-only, used for listing and querying backend users.
+
+These do not correlate 1:1 with objects defined in the API, but they are a close and convenient approximation.
+
+License
+-------
+This project and all code contained within it are released under the [MIT License](https://opensource.org/licenses/MIT). As stated in [CONTRIBUTING](CONTRIBUTING.md):
+
+> All contributions to this project will be released under the [MIT License](https://opensource.org/licenses/MIT). By submitting a pull request, you are agreeing to comply with this license and for any contributions to be released under it.

data/bin/antaeus-cli

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+
+require 'pry'
+require 'antaeus-sdk'
+
+include Antaeus::Resources
+client = Antaeus::UserAPIClient.instance
+
+puts "Starting up..."
+
+# Create or load a config file
+apprc_dir   = File.expand_path(File.join("~", ".antaeus"))
+config_file = File.expand_path(File.join(apprc_dir, "client.yml"))
+
+if File.readable?(config_file)
+  CONFIG = YAML.load_file(config_file)
+else
+  CONFIG = {
+    mode: 'singleuser',
+    group_name_attribute: 'cn',
+    base_url: 'http://localhost:8080',
+    login: 'username',
+    password: 'passw0rd',
+    debug: false
+  }
+  puts "Writing base config to `#{config_file}`"
+  FileUtils.mkdir_p(File.dirname(config_file))
+  File.open(config_file, 'w') {|f| f.write(CONFIG.to_yaml) }
+  puts "Please edit this config before running antaeus-cli"
+  exit 1
+end
+
+Pry.config.prompt = [ proc { "(antaeus)> " }, proc { "(antaeus)*" } ]
+
+binding.pry

data/lib/antaeus-sdk.rb

@@ -0,0 +1,58 @@
+# Standard Library requirements
+require 'fileutils'
+require 'base64'
+require 'yaml'
+require 'json'
+require 'ostruct'
+require 'singleton'
+require 'uri'
+require 'linguistics'
+Linguistics.use(:en)
+
+# External Requirements
+require 'crypt/blowfish'
+require 'rest-client'
+require 'will_paginate'
+require 'will_paginate/array'
+require 'addressable/uri'
+
+# Internal Requirements
+require 'antaeus-sdk/version'
+require 'antaeus-sdk/helpers/string'
+include Antaeus::Helpers
+
+require 'antaeus-sdk/exception'
+require 'antaeus-sdk/exceptions/approval_change_failed'
+require 'antaeus-sdk/exceptions/authentication_failure'
+require 'antaeus-sdk/exceptions/checkin_change_failed'
+require 'antaeus-sdk/exceptions/checkout_change_failed'
+require 'antaeus-sdk/exceptions/immutable_instance'
+require 'antaeus-sdk/exceptions/immutable_modification'
+require 'antaeus-sdk/exceptions/invalid_api_client'
+require 'antaeus-sdk/exceptions/invalid_config_data'
+require 'antaeus-sdk/exceptions/invalid_entity'
+require 'antaeus-sdk/exceptions/invalid_input'
+require 'antaeus-sdk/exceptions/invalid_options'
+require 'antaeus-sdk/exceptions/invalid_property'
+require 'antaeus-sdk/exceptions/invalid_where_query'
+require 'antaeus-sdk/exceptions/login_required'
+require 'antaeus-sdk/exceptions/missing_api_client'
+require 'antaeus-sdk/exceptions/missing_entity'
+require 'antaeus-sdk/exceptions/missing_path'
+require 'antaeus-sdk/exceptions/new_instance_with_id'
+require 'antaeus-sdk/config'
+Antaeus.config.load # Load config before requiring other classes
+
+require 'antaeus-sdk/api_client'
+require 'antaeus-sdk/api_info'
+require 'antaeus-sdk/guest_api_client'
+require 'antaeus-sdk/user_api_client'
+require 'antaeus-sdk/resource'
+require 'antaeus-sdk/resource_collection'
+require 'antaeus-sdk/resources/appointment'
+require 'antaeus-sdk/resources/guest'
+require 'antaeus-sdk/resources/group'
+require 'antaeus-sdk/resources/hook'
+require 'antaeus-sdk/resources/location'
+require 'antaeus-sdk/resources/remote_application'
+require 'antaeus-sdk/resources/user'

data/lib/antaeus-sdk/api_client.rb

@@ -0,0 +1,105 @@
+module Antaeus
+  # This class is the actual API client, which is a smart wrapper around RestClient
+  class APIClient
+    def self.instance
+      new
+    end
+
+    def initialize
+    end
+
+    # override this method
+    def authenticate(login, pass)
+      false
+    end
+
+    # override this method
+    def authenticated?
+      false
+    end
+
+    # override this method
+    def connect
+      false
+    end
+
+    def connected?
+      @rest_client ? true : false
+    end
+
+    def delete(uri)
+      client_action do
+        raw[Addressable::URI.escape(uri)].delete
+      end
+    end
+
+    def get(uri, data = nil)
+      client_action do
+        if data
+          JSON.load raw[Addressable::URI.escape(uri)].get(params: data)
+        else
+          JSON.load raw[Addressable::URI.escape(uri)].get
+        end
+      end
+    end
+
+    def post(uri, data)
+      client_action do
+        JSON.load raw[Addressable::URI.escape(uri)].post(json_escape(data.to_json))
+      end
+    end
+
+    def patch(uri, data)
+      client_action do
+        response = raw[Addressable::URI.escape(uri)].patch(json_escape(data.to_json))
+        if response && !response.empty?
+          JSON.load(response)
+        else
+          true
+        end
+      end
+    end
+
+    def put(uri, data)
+      client_action do
+        raw[Addressable::URI.escape(uri)].put(json_escape(data.to_json))
+      end
+    end
+
+    def raw
+      @rest_client
+    end
+
+    # This needs to be caught by whatever is using the SDK to get new user creds
+    def refresh_token
+      @rest_client = nil
+      raise Exceptions::LoginRequired
+    end
+
+    private
+
+    def json_escape(s)
+      json_escape = {
+        '&' => '\u0026',
+        '>' => '\u003e',
+        '<' => '\u003c',
+        '%' => '\u0025',
+        "\u2028" => '\u2028',
+        "\u2029" => '\u2029'
+      }
+      json_escape_regex = /[\u2028\u2029&><%]/u
+
+      s.to_s.gsub(json_escape_regex, json_escape)
+    end
+
+    def client_action(&block)
+      begin
+        yield if connect
+      rescue RestClient::Exception => e
+        raise e, e.response unless e.http_code == 401 # This rescue only helps with token refreshing
+        refresh_token
+        yield if connect
+      end
+    end # client_action()
+  end
+end

data/lib/antaeus-sdk/api_info.rb

@@ -0,0 +1,47 @@
+module Antaeus
+  module APIInfo
+    def self.version(options = {})
+      validate_options(options)
+
+      options[:client].get('/info/version')['api']['version']
+    end
+
+    def self.status(options = {})
+      validate_options(options)
+
+      options[:client].get('/info/status')['api']['status']
+    end
+
+    def self.capabilities(options = {})
+      validate_options(options)
+
+      options[:client].get('/info/capabilities')['api']['capabilities']
+    end
+
+    def self.plugins(options = {})
+      validate_options(options)
+
+      options[:client].get('/info/plugins')['api']['plugins']
+    end
+
+    def self.metrics(options = {})
+      validate_options(options)
+
+      options[:client].get('/info/metrics')['api']['metrics']
+    end
+
+    def self.me(options = {})
+      validate_options(options)
+
+      options[:client].get('/info/me')['current_user']
+    end
+
+    private
+
+    def self.validate_options(options)
+      raise Exceptions::InvalidOptions unless options.is_a?(Hash)
+      raise Exceptions::MissingAPIClient unless options[:client]
+      raise Exceptions::InvalidAPIClient unless options[:client].is_a?(APIClient)
+    end
+  end
+end

data/lib/antaeus-sdk/config.rb

@@ -0,0 +1,54 @@
+# A generic way of constructing a mergeable configuration
+class Antaeus::Config < OpenStruct
+  # Construct a base config using the following order of precedence:
+  #   * environment variables
+  #   * YAML file
+  #   * defaults
+  def load
+    # First, apply the defaults
+    defaults = {
+      group_name_attribute: :cn,
+      user_login_attribute: :uid,
+      user_firstname_attribute: :givenName,
+      user_lastname_attribute: :sn,
+      user_mail_attribute: :mail,
+      base_url: 'http://localhost:8080',
+      login: 'username',
+      password: 'p@assedWard!'
+    }
+    merge defaults
+
+    # Then apply the config file, if one exists
+    begin
+      apprc_dir = File.expand_path(File.join('~', '.antaeus'))
+      config_file = File.expand_path(File.join(apprc_dir, 'client.yml'))
+      merge YAML.load_file(config_file) if File.readable?(config_file)
+    rescue => e
+      puts "Unable to read from ~/.antaeus/client.yml"
+    end
+
+    # Finally, apply any environment variables specified
+    env_conf = {}
+    defaults.keys.each do |key|
+      antaeus_key = "ANTAEUS_#{key}".upcase
+      env_conf[key] = ENV[antaeus_key] if ENV.key?(antaeus_key)
+    end
+    merge env_conf unless env_conf.empty?
+  end
+
+  def merge(data)
+    raise Exceptions::InvalidConfigData unless data.is_a?(Hash)
+    data.each do |k, v|
+      self[k.to_sym] = v
+    end
+  end
+end
+
+# Make the config available as a singleton
+module Antaeus
+  class << self
+    def config
+      @config ||= Config.new
+    end
+  end
+end