alman 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 01e914cb37b2e9dac560acb9ed5dc39b55eb5ace
+  data.tar.gz: 5913e8b2d5ede9e2d6a5dc2b386a92b8a98dfb00
+SHA512:
+  metadata.gz: 6223e1fbf869c47d18c7ce6f0115d043be7ca2ff220a8cf4423e8e6f3fb9aade4545302135135cc6d19f1ce86a154911303ba2f4abdda6a9f02492fab2ddffab
+  data.tar.gz: 2e18722a1195ce2f6ca9ab5ead648da353abca7defd619050508c85c6059f035803f5916b4f452fba159cfaa61a3b6d3debf6fc00459827a89abdcd03220bea3

data/.gitignore

@@ -0,0 +1,4 @@
+pkg
+Gemfile.lock
+*.gem
+.ruby-version

data/.travis.yml

@@ -0,0 +1,16 @@
+language: ruby
+
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - 2.0.0
+  - 2.1
+  - 2.2
+
+gemfile:
+  - gemfiles/default-with-activesupport.gemfile
+  - gemfiles/json.gemfile
+  - gemfiles/yajl.gemfile
+
+sudo: false

data/Gemfile

@@ -0,0 +1,8 @@
+source "https://rubygems.org"
+gemspec
+
+if Gem::Version.new(RUBY_VERSION.dup) < Gem::Version.new('1.9.3')
+  gem 'i18n', '< 0.7'
+  gem 'rest-client', '~> 1.6.8'
+  gem 'activesupport', '~> 3.2'
+end

data/README.md

@@ -0,0 +1,103 @@
+# Alman Ruby Bindings
+
+[![API Library via Apibits.com](http://apibits.com/assets/images/apibits-badge.png)](http://apibits.com)
+
+
+## Installation
+
+You don't need this source code unless you want to modify the gem. If
+you just want to use the Alman Ruby bindings, you should run:
+
+```bash
+gem install alman
+```
+
+If you want to build & install the gem from source:
+
+```bash
+gem build alman.gemspec
+gem install alman-0.0.1.gem
+```
+
+## Documentation
+
+Full documentation is available at [http://almanapi.com/docs](http://almanapi.com/docs).
+
+
+## Requirements
+
+* Ruby 1.8.7 or above. (Ruby 1.8.6 may work if you load
+  ActiveSupport.) For Ruby versions before 1.9.2, you'll need to add this to your Gemfile:
+
+```ruby
+if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('1.9.2')
+  gem 'rest-client', '~> 1.6.8'
+end
+```
+
+* rest-client, json
+
+
+## Bundler
+
+If you are installing via bundler, you should be sure to use the https
+rubygems source in your Gemfile, as any gems fetched over http could potentially be compromised.
+
+```ruby
+source 'https://rubygems.org'
+
+gem 'rails'
+gem 'alman'
+```
+
+## Using the library
+
+The following section covers some general info about this API library. If you are looking for documentation covering the entire API, check here: [http://almanapi.com/docs](http://almanapi.com/docs).
+
+### Params and Headers
+
+All API methods accept 2 optional arguments - the params and headers. For example, if you had `SomeResource` and wanted to call `#some_method(some_arg)`, all of the following would be valid:
+
+```ruby
+# With no custom params or headers
+Alman::SomeResource.some_method(some_arg)
+
+# With only custom params
+Alman::SomeResource.some_method(some_arg, params)
+
+# With only custom headers
+Alman::SomeResource.some_method(some_arg, nil, headers)
+
+# With both custom params and headers
+Alman::SomeResource.some_method(some_arg, params, headers)
+```
+
+This is mostly useful when creating new resources, or when trying to use an API endpoint that supports pagination.
+
+
+### Using Multiple API Keys
+
+The API library was designed to support both developers who plan to only use one API key, as well as developers who may need to use multiple API keys in the same server.
+
+By default most resource lookups use code like this:
+
+```ruby
+Alman.api_key = "your-api-key"
+test = Alman::Calendar.retrieve(id)
+```
+
+but since the API key is set on the module, this could cause issues if you need to use multiple API keys. To get around this, simply use one of the API clients located in the `clients` folder. For example:
+
+```ruby
+client = Alman::DefaultClient.new("your-api-key")
+test = client.calendars.retreive(id)
+```
+
+The results from each will be the same, so if you prefer the client version you are welcome to use it even if you aren't using multiple API keys in production.
+
+
+## Development
+
+Test cases can be run with: `bundle exec rake test`
+
+We welcome suggestions and feedback from our users :D

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rake/testtask'
+require 'yaml'
+
+task :default => [:test]
+
+Rake::TestTask.new do |t|
+  t.pattern = './test/**/[^_]*_test.rb'
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/alman.gemspec

@@ -0,0 +1,29 @@
+$:.unshift(File.join(File.dirname(__FILE__), 'lib'))
+
+require 'alman/version'
+
+spec = Gem::Specification.new do |s|
+  s.name = 'alman'
+  s.summary = 'Ruby bindings for Alman API'
+  s.description = 'Alman is a calendar scheduling API.'
+  s.homepage = 'http://almanapi.com/docs'
+  s.authors = ['Apibits.com']
+  s.email = ['libraries@apibits.com']
+  s.version = Alman::VERSION
+  s.license = 'MIT'
+
+  s.add_dependency('rest-client', '~> 1.4')
+  s.add_dependency('mime-types', '>= 1.25', '< 3.0')
+  s.add_dependency('json', '~> 1.8.1')
+
+  s.add_development_dependency('mocha', '~> 0.13.2')
+  s.add_development_dependency('shoulda', '~> 3.4.0')
+  s.add_development_dependency('test-unit')
+  s.add_development_dependency('rake')
+
+  s.files = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- test/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ['lib']
+end
+

data/bin/alman-console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+irb = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb'
+
+libs =  " -r irb/completion"
+libs <<  " -r #{File.dirname(__FILE__) + '/../lib/alman'}"
+puts "Loading Alman gem"
+exec "#{irb} #{libs} --simple-prompt"

data/gemfiles/default-with-activesupport.gemfile

@@ -0,0 +1,10 @@
+source "https://rubygems.org"
+gemspec :path => File.join(File.dirname(__FILE__), "..")
+
+if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('1.9.3')
+  gem 'i18n', '< 0.7'
+  gem 'rest-client', '~> 1.6.8'
+  gem 'activesupport', '~> 3.2'
+else
+  gem 'activesupport'
+end

data/gemfiles/json.gemfile

@@ -0,0 +1,12 @@
+source "https://rubygems.org"
+gemspec :path => File.join(File.dirname(__FILE__), "..")
+
+if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('1.9.3')
+  gem 'i18n', '< 0.7'
+  gem 'rest-client', '~> 1.6.8'
+  gem 'activesupport', '~> 3.2'
+else
+  gem 'activesupport'
+end
+
+gem 'json'

data/gemfiles/yajl.gemfile

@@ -0,0 +1,12 @@
+source "https://rubygems.org"
+gemspec :path => File.join(File.dirname(__FILE__), "..")
+
+if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('1.9.3')
+  gem 'i18n', '< 0.7'
+  gem 'rest-client', '~> 1.6.8'
+  gem 'activesupport', '~> 3.2'
+else
+  gem 'activesupport'
+end
+
+gem 'yajl-ruby'

data/lib/alman.rb

@@ -0,0 +1,68 @@
+# Alman Ruby bindings
+# API Docs are located at http://almanapi.com/docs
+require 'cgi'
+require 'set'
+require 'openssl'
+require 'rest_client'
+require 'json'
+require 'base64'
+
+# Version
+require 'alman/version'
+
+# Errors
+require 'alman/errors/alman_error'
+require 'alman/errors/api_error'
+require 'alman/errors/api_connection_error'
+require 'alman/errors/authentication_error'
+
+# Wrapper around RestClient
+require 'alman/apibits/requester'
+
+# Builders for creating API methods.
+require 'alman/apibits/path_builder'
+require 'alman/apibits/headers_builder'
+require 'alman/apibits/params_builder'
+require 'alman/apibits/api_method'
+
+# Generic resources
+require 'alman/apibits/api_endpoint'
+require 'alman/apibits/api_client'
+require 'alman/apibits/api_object'
+require 'alman/apibits/api_resource'
+require 'alman/apibits/api_list'
+require 'alman/apibits/util'
+
+# API specific resources
+require 'alman/resources/calendar'
+require 'alman/resources/vacancy'
+require 'alman/resources/booking'
+
+# API specific endpoints
+require 'alman/endpoints/calendars_endpoint'
+require 'alman/endpoints/calendar_vacancies_endpoint'
+require 'alman/endpoints/vacancies_endpoint'
+require 'alman/endpoints/vacancy_bookings_endpoint'
+require 'alman/endpoints/bookings_endpoint'
+
+# API specific clients
+require 'alman/clients/default_client'
+
+
+module Alman
+  @api_base = "http://almanapi.com/api/v0"
+  @api_staging = ""
+  @api_version = "v0"
+  @support_email = "support@almanapi.com"
+  @docs_url = "http://almanapi.com/docs"
+
+  class << self
+    attr_accessor :api_base, :api_version
+    attr_reader :api_staging, :support_email, :docs_url
+    attr_accessor :api_key
+  end
+
+  def self.default_client
+    DefaultClient.new(Alman.api_key)
+  end
+end

data/lib/alman/apibits/api_client.rb

@@ -0,0 +1,28 @@
+module Alman
+  class ApiClient
+    attr_accessor :headers, :params
+
+    def initialize(headers, params)
+      self.refresh_from(headers, params)
+    end
+
+    def refresh_from(headers, params)
+      @headers = headers
+      @params = params
+      self
+    end
+
+    def execute(api_method)
+      api_method.headers = ParamsBuilder.merge(api_method.headers, @headers)
+      api_method.params = ParamsBuilder.merge(api_method.params, @params)
+      api_method.execute
+    end
+
+    def inspect
+      "#<#{self.class}:0x#{self.object_id.to_s(16)}> Headers: " +
+        JSON.pretty_generate(@headers) + ", Params: " +
+        JSON.pretty_generate(@params)
+    end
+
+  end
+end

data/lib/alman/apibits/api_endpoint.rb

@@ -0,0 +1,11 @@
+module Alman
+  class ApiEndpoint
+    attr_accessor :client
+    attr_accessor :parent
+
+    def initialize(client, parent=nil)
+      @client = client
+      @parent = parent
+    end
+  end
+end

data/lib/alman/apibits/api_list.rb

@@ -0,0 +1,88 @@
+module Alman
+  class ApiList < ApiResource
+    include Enumerable
+
+    attr_reader :api_method
+    attr_reader :client
+    attr_reader :data
+    attr_reader :klass
+
+    def initialize(klass, json={}, api_method=nil, client=nil)
+      if klass.is_a?(Class)
+        @klass = klass
+      else
+        @klass = Util.constantize(klass)
+      end
+
+      refresh_from(json, api_method, client)
+    end
+
+    def refresh_from(json, api_method=nil, client=nil)
+      unless json.is_a?(Hash)
+        json = {
+          :data => json
+        }
+      end
+      json = Util.symbolize_keys(json)
+
+      clear_api_attributes
+      @api_method = api_method
+      @client = client
+      @data = []
+      @json = Util.sorta_deep_clone(json)
+
+      json.each do |k, v|
+        if k.to_sym == :data
+          if v.respond_to?(:map)
+            instance_variable_set("@#{k}", v.map{ |i| @klass.new(i, @api_method, @client) })
+          else
+            instance_variable_set("@#{k}", v || [])
+          end
+        elsif self.class.api_attribute_names.include?(k)
+          instance_variable_set("@#{k}", determine_api_attribute_value(k, v))
+        end
+      end
+      self
+    end
+
+    def [](k)
+      data[k]
+    end
+
+    def []=(k, v)
+      data[k]=v
+    end
+
+    def last
+      data.last
+    end
+
+    def length
+      data.length
+    end
+
+    def each(&blk)
+      data.each(&blk)
+    end
+
+    def inspect
+      "#<#{self.class}[#{@klass}]:0x#{self.object_id.to_s(16)}> Data: " + JSON.pretty_generate(inspect_data)
+    end
+
+    def inspect_data
+      ret = []
+      data.each do |d|
+        if d.respond_to?(:inspect_nested)
+          ret << d.inspect_nested
+        else
+          ret << d
+        end
+      end
+      ret
+    end
+
+    @api_attributes = {
+      :data => { :readonly => true }
+    }
+  end
+end

data/lib/alman/apibits/api_method.rb

@@ -0,0 +1,95 @@
+module Alman
+  class ApiMethod
+
+    attr_accessor :path
+    attr_accessor :method
+    attr_accessor :params
+    attr_accessor :headers
+
+    attr_accessor :response_body
+    attr_accessor :response_code
+    attr_accessor :error
+
+    attr_accessor :api_base
+
+    def initialize(method, path, params, headers, object)
+      @api_base = api_base || Alman.api_base
+
+      @method = method.to_sym
+      @path = PathBuilder.build(path, object, params)
+      @params = ParamsBuilder.build(params)
+      @headers = HeadersBuilder.build(headers)
+    end
+
+    def execute
+      begin
+        response = Requester.request(method, url, params, headers)
+        @response_body = response.body
+        @response_code = response.code
+      rescue StandardError => e
+        @response_body = e.http_body if e.respond_to?(:http_body)
+        @response_code = e.http_code if e.respond_to?(:http_code)
+        @error = compose_error(e)
+        raise @error
+      end
+
+
+      response_json
+    end
+
+    def url
+      "#{api_base}#{@path}"
+    end
+
+    def response_json
+      return @json if @json
+      begin
+        @json = Util.symbolize_keys(JSON.parse(@response_body))
+      rescue JSON::ParserError
+        @error = ApiError.new("Unable to parse the server response as JSON.", self)
+        raise @error
+      end
+      @json
+    end
+
+    def compose_error(error)
+      msg = "An error occured while making the API call."
+
+      case error
+      when RestClient::ExceptionWithResponse
+        return error_with_response(error)
+
+      when RestClient::RequestTimeout
+        msg = "The request timed out while making the API call."
+
+      when RestClient::ServerBrokeConnection
+        msg = "The connection to the server broke before the request completed."
+
+      when SocketError
+        msg = "An unexpected error occured while trying to connect to " \
+          "the API. You may be seeing this message because your DNS is " \
+          "not working. To check, try running 'host #{Alman.api_base}' "\
+          "from the command line."
+
+      else
+        msg = "An unexpected error occured. If this problem persists let us " \
+          "know at #{Alman.support_email}."
+      end
+
+      return ApiConnectionError.new(msg, self)
+    end
+
+    # Handle a few common cases.
+    def error_with_response(error)
+      case @response_code
+      when 400, 404
+        return ApiError.new(@response_body || "Invalid request. Please check the URL and parameters.", self)
+      when 401
+        return AuthenticationError.new(@response_body || "Authentication failed.", self)
+      else
+        return ApiError.new(@response_body || "An error occured while making the API call.", self)
+      end
+    end
+
+  end
+end