bootic_client 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4311719bc6b53b09e5026c67183f7313c491f48f
+  data.tar.gz: 7f85b7946a404ae8b32019cb05df811ce6a60709
+SHA512:
+  metadata.gz: 125c0102f1890b005ef8e4ff9ca74f4f597d16c8c542c097edb1e5541ee17c05edc3cd64b0200e7dc61282bd1d5b72dcf8a32e8f3b5f1ce2e0f11ee4907e86f9
+  data.tar.gz: f9b42eeb52e5e031b35d3b2d3c25a20408e0753348c60e358b3fd8fa8f198a21918c8958377a809484f65304ff2b60a1209f1081eb8cc36c75da6ab34e45d187

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.0.0

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in bootic_client.gemspec
+gemspec
+
+group :test do
+  gem 'byebug'
+  gem 'vcr', '~> 2.4'
+  gem 'webmock', '>= 1.9'
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Ismael Celis
+
+MIT License
+
+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,115 @@
+[![Build Status](https://travis-ci.org/bootic/bootic_client.rb.svg?branch=master)](https://travis-ci.org/bootic/bootic_client.rb)
+
+## WORK IN PROGRESS
+
+# BooticClient
+
+Official Ruby client for the [Bootic API](https://developers.bootic.net)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'bootic_client'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install bootic_client
+
+## Usage
+
+### Configure with you app's credentials
+
+```ruby
+BooticClient.configure do |c|
+  c.client_id = ENV['BOOTIC_CLIENT_ID']
+  c.client_secret = ENV['BOOTIC_CLIENT_SECRET']
+  c.logger = Logger.new(STDOUT)
+  c.logging = true
+  c.cache_store = Rails.cache
+end
+```
+
+### Using with an existing access token
+
+```ruby
+bootic = BooticClient.client(:authorized, access_token: 'beidjbewjdiedue...', logging: true)
+
+root = bootic.root
+
+if root.has?(:products)
+  # All products
+  all_products = root.products(q: 'xmas presents')
+  all_products.total_items # => 23443
+  all_products.each do |product|
+    puts product.title
+    puts product.price
+  end
+
+  if all_product.has?(:next)
+    next_page = all_products.next
+    next_page.each{...}
+  end
+end
+```
+
+## 1. Refresh token flow (web apps)
+
+In this flow you first get a token by authorizing an app. ie. using [omniauth-bootic](https://github.com/bootic/omniauth-bootic)
+
+```ruby
+def client
+  @client ||= BooticClient.client(:authorized, access_token: session[:access_token]) do |new_token|
+    session[:access_token] = new_token
+  end
+end
+```
+
+
+## 2. User-less flow (client credentials - automated scripts)
+
+```ruby
+client = BooticClient.client(:client_credentials, scope: 'admin', access_token: some_store[:access_token]) do |new_token|
+  some_store[:access_token] = new_token
+end
+```
+
+
+## Cache storage
+
+`BooticClient` honours HTTP caching headers included in API responses (such as `ETag` and `Last-Modified`).
+
+By default a simple memory store is used. It is recommended that you use a distributed store in production, such as Memcache. In Rails applications you can use the `Rails.cache` interface.
+
+```ruby
+BooticClient.configure do |c|
+  ...
+  c.cache_store = Rails.cache
+end
+```
+
+Outside of Rails, BooticClient ships with a wrapper around the [Dalli](https://github.com/mperham/dalli) memcache client. 
+You must include Dalli in your Gemfile and require the wrapper explicitely.
+
+```ruby
+require 'bootic_client/stores/memcache'
+CACHE_STORE = BooticClient::Stores::Memcache.new(ENV['MEMCACHE_SERVER'])
+
+BooticClient.configure do |c|
+  ...
+  c.cache_store = CACHE_STORE
+end
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bootic_client.gemspec

@@ -0,0 +1,33 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'bootic_client/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "bootic_client"
+  spec.version       = BooticClient::VERSION
+  spec.authors       = ["Ismael Celis"]
+  spec.email         = ["ismaelct@gmail.com"]
+  spec.description   = %q{Official Ruby client for the Bootic API}
+  spec.summary       = %q{Official Ruby client for the Bootic API}
+  spec.homepage      = "https://developers.bootic.net"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "faraday", '~> 0.9'
+  spec.add_dependency "uri_template", '~> 0.7'
+  spec.add_dependency "faraday_middleware", '~> 0.9'
+  spec.add_dependency "faraday-http-cache", '~> 0.4'
+  spec.add_dependency "net-http-persistent", '~> 2.9'
+  spec.add_dependency "oauth2"
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "jwt"
+  spec.add_development_dependency "dalli"
+end

data/lib/bootic_client/client.rb

@@ -0,0 +1,73 @@
+require 'faraday'
+require 'faraday_middleware'
+require 'faraday-http-cache'
+require "bootic_client/errors"
+require 'faraday/adapter/net_http_persistent'
+
+module BooticClient
+
+  class Client
+
+    USER_AGENT = "[BooticClient v#{VERSION}] Ruby-#{RUBY_VERSION} - #{RUBY_PLATFORM}".freeze
+
+    attr_reader :options, :api_root
+
+    def initialize(api_root, options = {}, &block)
+      @api_root = api_root
+      @options = {
+        access_token: nil,
+        logging: false
+      }.merge(options.dup)
+
+      @options[:cache_store] = @options[:cache_store] || Faraday::HttpCache::MemoryStore.new
+
+      conn &block if block_given?
+    end
+
+    def get_and_wrap(href, wrapper_class, query = {})
+      wrapper_class.new get(href, query).body, self
+    end
+
+    def get(href, query = {})
+      validate_request!
+
+      resp = conn.get do |req|
+        req.url href
+        req.params.update(query)
+        req.headers['Authorization'] = "Bearer #{options[:access_token]}"
+        req.headers['User-Agent'] = USER_AGENT
+      end
+
+      raise_if_invalid! resp
+
+      resp
+    end
+
+    protected
+
+    def conn(&block)
+      @conn ||= Faraday.new(url: api_root) do |f|
+        cache_options = {shared_cache: false, store: options[:cache_store]}
+        cache_options[:logger] = options[:logger] if options[:logging]
+
+        f.use :http_cache, cache_options
+        f.response :logger, options[:logger] if options[:logging]
+        f.response :json
+        yield f if block_given?
+        f.adapter :net_http_persistent
+      end
+    end
+
+    def validate_request!
+      raise NoAccessTokenError, "Missing access token" unless options[:access_token]
+    end
+
+    def raise_if_invalid!(resp)
+      raise ServerError, "Server Error" if resp.status > 499
+      raise NotFoundError, "Not Found" if resp.status == 404
+      raise UnauthorizedError, "Unauthorized request" if resp.status == 401
+      raise AccessForbiddenError, "Access Forbidden" if resp.status == 403
+    end
+  end
+
+end

data/lib/bootic_client/entity.rb

@@ -0,0 +1,125 @@
+require "bootic_client/relation"
+require 'ostruct'
+
+module BooticClient
+  class Entity
+
+    CURIE_EXP = /(.+):(.+)/.freeze
+    CURIES_REL = 'curies'.freeze
+    SPECIAL_PROP_EXP = /^_.+/.freeze
+
+    attr_reader :curies, :entities
+
+    def initialize(attrs, client, top = self)
+      @attrs, @client, @top = attrs, client, top
+      build!
+    end
+
+    def [](key)
+      properties[key.to_sym]
+    end
+
+    def has?(prop_name)
+      has_property?(prop_name) || has_entity?(prop_name) || has_rel?(prop_name)
+    end
+
+    def inspect
+      %(#<#{self.class.name} props: [#{properties.keys.join(', ')}] rels: [#{rels.keys.join(', ')}] entities: [#{entities.keys.join(', ')}]>)
+    end
+
+    def properties
+      @properties ||= attrs.select{|k,v| !(k =~ SPECIAL_PROP_EXP)}.each_with_object({}) do |(k,v),memo|
+        memo[k.to_sym] = Entity.wrap(v)
+      end
+    end
+
+    def links
+      @links ||= attrs.fetch('_links', {})
+    end
+
+    def self.wrap(obj)
+      case obj
+      when Hash
+        OpenStruct.new(obj)
+      when Array
+        obj.map{|e| wrap(e)}
+      else
+        obj
+      end
+    end
+
+    def method_missing(name, *args, &block)
+      if !block_given?
+        if has_property?(name)
+          self[name]
+        elsif has_entity?(name)
+          entities[name]
+        elsif has_rel?(name)
+          rels[name].get(*args)
+        else
+          super
+        end
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      has?(method_name)
+    end
+
+    def has_property?(prop_name)
+      properties.has_key? prop_name.to_sym
+    end
+
+    def has_entity?(prop_name)
+      entities.has_key? prop_name.to_sym
+    end
+
+    def has_rel?(prop_name)
+      rels.has_key? prop_name.to_sym
+    end
+
+    def each(&block)
+      iterable? ? entities[:items].each(&block) : [self].each(&block)
+    end
+
+    def rels
+      @rels ||= (
+        links = attrs.fetch('_links', {})
+        links.each_with_object({}) do |(rel,rel_attrs),memo|
+          if rel =~ CURIE_EXP
+            _, curie_namespace, rel = rel.split(CURIE_EXP)
+            if curie = curies.find{|c| c['name'] == curie_namespace}
+              rel_attrs['docs'] = Relation.expand(curie['href'], rel: rel)
+            end
+          end
+          if rel != CURIES_REL
+            rel_attrs['name'] = rel
+            memo[rel.to_sym] = Relation.new(rel_attrs, client, Entity)
+          end
+        end
+      )
+    end
+
+    protected
+
+    attr_reader :client, :top, :attrs
+
+    def iterable?
+      has_entity?(:items) && entities[:items].respond_to?(:each)
+    end
+
+    def build!
+      @curies = top.links.fetch('curies', [])
+
+      @entities = attrs.fetch('_embedded', {}).each_with_object({}) do |(k,v),memo|
+        memo[k.to_sym] = if v.kind_of?(Array)
+          v.map{|ent_attrs| Entity.new(ent_attrs, client, top)}
+        else
+          Entity.new(v, client, top)
+        end
+      end
+    end
+  end
+end

data/lib/bootic_client/errors.rb

@@ -0,0 +1,9 @@
+module BooticClient
+  class TransportError < StandardError; end
+  class ServerError < TransportError; end
+  class NotFoundError < ServerError; end
+  class TokenError < ServerError; end
+  class UnauthorizedError < TokenError; end
+  class AccessForbiddenError < TokenError; end
+  class NoAccessTokenError < TokenError; end
+end

data/lib/bootic_client/relation.rb

@@ -0,0 +1,60 @@
+require 'uri_template'
+require "bootic_client/entity"
+
+module BooticClient
+
+  class Relation
+
+    def initialize(attrs, client, wrapper_class = Entity)
+      @attrs, @client, @wrapper_class = attrs, client, wrapper_class
+    end
+
+    def inspect
+      %(#<#{self.class.name} #{attrs.inspect}>)
+    end
+
+    def href
+      attrs['href']
+    end
+
+    def templated?
+      !!attrs['templated']
+    end
+
+    def name
+      attrs['name']
+    end
+
+    def title
+      attrs['title']
+    end
+
+    def type
+      attrs['type']
+    end
+
+    def docs
+      attrs['docs']
+    end
+
+    def get(opts = {})
+      if templated?
+        client.get_and_wrap uri.expand(opts), wrapper_class
+      else
+        client.get_and_wrap href, wrapper_class, opts
+      end
+    end
+
+    def self.expand(href, opts = {})
+      URITemplate.new(href).expand(opts)
+    end
+
+    protected
+    attr_reader :wrapper_class, :client, :attrs
+
+    def uri
+      @uri ||= URITemplate.new(href)
+    end
+  end
+
+end

data/lib/bootic_client/stores/memcache.rb

@@ -0,0 +1,33 @@
+require 'dalli'
+
+module BooticClient
+  module Stores
+    class Memcache
+      attr_reader :client
+
+      def initialize(server_hosts, dalli_options = {})
+        @client = Dalli::Client.new(Array(server_hosts), dalli_options)
+      end
+
+      def read(key)
+        @client.get key.to_s
+      end
+
+      def write(key, data, ttl = nil)
+        @client.set key.to_s, data, ttl
+      end
+
+      def get(key)
+        @client.get key
+      end
+
+      def set(key, data, ttl = nil)
+        @client.set key, data, ttl
+      end
+
+      def stats
+        @client.stats
+      end
+    end
+  end
+end

data/lib/bootic_client/strategies/authorized.rb

@@ -0,0 +1,38 @@
+require 'bootic_client/strategies/strategy'
+
+module BooticClient
+  module Strategies
+
+    class Authorized < Strategy
+      protected
+
+      def validate!(options)
+        raise "options MUST include access_token" unless options[:access_token]
+      end
+
+      def get_token
+        # The JWT grant must have an expiration date, in seconds since the epoch. 
+        # For most cases a few seconds should be enough.
+        exp = Time.now.utc.to_i + 5
+
+        # Use the "assertion" flow to exchange the JWT grant for an access token
+        access_token = auth.assertion.get_token(
+          hmac_secret: config.client_secret,
+          iss: config.client_id,
+          prn: client.options[:access_token],
+          aud: 'api',
+          exp: exp
+        )
+
+        access_token.token
+      end
+
+      def auth
+        @auth ||= OAuth2::Client.new(nil, nil, site: config.auth_host)
+      end
+    end
+
+  end
+
+  strategies[:authorized] = Strategies::Authorized
+end

data/lib/bootic_client/strategies/client_credentials.rb

@@ -0,0 +1,19 @@
+require 'bootic_client/strategies/strategy'
+
+module BooticClient
+  module Strategies
+
+    class ClientCredentials < Strategy
+      protected
+      def get_token
+        opts = {}
+        opts['scope'] = options.delete(:scope) if options[:scope]
+        token = auth.client_credentials.get_token(opts, 'auth_scheme' => 'basic')
+        token.token
+      end
+    end
+
+  end
+
+  strategies[:client_credentials] = Strategies::ClientCredentials
+end

data/lib/bootic_client/strategies/strategy.rb

@@ -0,0 +1,59 @@
+require 'oauth2'
+
+module BooticClient
+  module Strategies
+    class Strategy
+
+      def initialize(config, client_opts = {}, &on_new_token)
+        @config, @options, @on_new_token = config, client_opts, (on_new_token || Proc.new)
+        raise "MUST include client_id" unless config.client_id
+        raise "MUST include client_secret" unless config.client_secret
+        raise "MUST include api_root" unless config.api_root
+        validate! @options
+      end
+
+      def root
+        get config.api_root
+      end
+
+      def get(href, query = {})
+        begin
+          client.get_and_wrap(href, Entity, query)
+        rescue TokenError => e
+          new_token = get_token
+          client.options[:access_token] = new_token
+          on_new_token.call new_token
+          client.get_and_wrap(href, Entity, query)
+        end
+      end
+
+      def inspect
+        %(#<#{self.class.name} cid: #{config.client_id} root: #{config.api_root} auth: #{config.auth_host}>)
+      end
+
+      protected
+
+      attr_reader :config, :options, :on_new_token
+
+      def validate!(options)
+        
+      end
+
+      def get_token
+        raise "Implement this in subclasses"
+      end
+
+      def auth
+        @auth ||= OAuth2::Client.new(
+          config.client_id,
+          config.client_secret,
+          site: config.auth_host
+        )
+      end
+
+      def client
+        @client ||= Client.new(config.api_root, options)
+      end
+    end
+  end
+end

data/lib/bootic_client/version.rb

@@ -0,0 +1,3 @@
+module BooticClient
+  VERSION = "0.0.1"
+end