blomming_api 0.4.1

data/lib/blomming_api/help.rb

@@ -0,0 +1,140 @@
+require 'method_source'
+
+module BlommingApi
+
+  AUTHORS = ["Giorgio Robino"]
+  EMAILS = ["giorgio.robino@gmail.com"]
+  SUMMARY = %q{www.blomming.com social commerce API's wrapper}
+  DESCRIPTION = %q{www.blomming.com social commerce API's wrapper: supply a client access layer that embed authentication and communication details, supply API endpoints wrappers.}
+  HOMEPAGE = "https://github.com/solyaris/blomming_api"
+
+  def BlommingApi::about
+  	"\tgem      : blomming_api (v.#{BlommingApi::VERSION})\n"\
+    "\tsummary  : #{BlommingApi::SUMMARY}\n"\
+    "\tauthors  : #{BlommingApi::AUTHORS.join(',')} (#{BlommingApi::EMAILS.join(',')})\n"\
+    "\thomepage : #{BlommingApi::HOMEPAGE}\n"
+  end
+
+  def BlommingApi::endpoints_help
+    puts "BUY endpoints available methods:\n\n"
+
+    buy_endpoints_methods = BlommingApi::BuyEndpoints.instance_methods(false)
+    
+    buy_endpoints_methods.each do |method_name|
+      display_method_info method_name
+    end 
+
+    puts "SELL endpoints available methods:\n\n"
+
+    sell_endpoints_methods = BlommingApi::SellEndpoints.instance_methods(false)
+    
+    sell_endpoints_methods.each do |method_name|
+      display_method_info method_name
+    end
+  end
+
+  def BlommingApi::display_method_info (method_name) 
+    method_comment = BlommingApi::Client.instance_method(method_name.to_sym).comment
+    
+    #method_comment.gsub! "#", "\t#"
+
+    method_source = BlommingApi::Client.instance_method(method_name.to_sym).source
+
+    method_def = method_source.split("\n").first.strip[/def (?<match>.*)/,"match"]
+    location = BlommingApi::Client.instance_method(method_name.to_sym).source_location
+
+    puts "#{method_comment}"
+    puts "\t#{method_def}"
+    puts "\tfile: #{location.first}"
+    puts "\tline: #{location.last}"
+  end
+  private_class_method :display_method_info
+
+
+  def BlommingApi::authentication_help
+    <<-CONFIGURATION_HELP
+Authentication set-up
+
+In order to be granted to access to Blomming API, each client must be identified by some credential values (oauth server authentication). 
+
+Get your Blomming API credentials
+=================================
+
+API credentials are generated by Blomming tech team for a per 3rd part application use. Please contact [api@blomming.com](mailto:api@blomming.com) and explain briefly why do you need them and how do you plan to use Blomming service. Blomming tech team will be happy to give you the full access to API!
+
+Buy Services Authentication
+---------------------------
+
+To access Blomming APIs, each client must be identified by two credential values required as parameters of initial Blomming OAuth server bearer token request:
+
+- *Application ID*
+- *Secret*
+
+Sell Services Authentication
+----------------------------
+
+Application ID and Secret values, are all you need to use buy services, but in case of sell services, you must authenticate supplying also your Blomming account cusername and password:
+
+- *Username*
+- *Password*
+
+
+Set-up your *blommimg_api* configuration file 
+=============================================
+
+Using the blomming_api gem, a client must be "initialized" with a YAML configuration file (.yml), in order to store all Blomming API credentials data and some default API values, among others:
+
+- *domain* (production/staging API urls) 
+- *api_version* (API release number)
+
+
+You have to set-up all data on a blommimg_api YAML configuration file `<your_config_file.yml>`, following these two possible skeletons:
+
+
+Config file for *BUY services* authentication
+---------------------------------------------
+
+Config file example: `your/path/to/buy_services_stage_config.yml` :
+
+    description: my account for buy services, access to staging server 
+
+    services: buy
+
+    client_id: __copy_here_your_blomming_api_client_id__
+    client_secret: __copy_here_your_blomming_api_client_secret__
+
+    domain: https://blomming-api-staging.herokuapp.com
+    api_version: /v1
+
+    default_currency: USD
+    default_locale: US
+
+    verbose: false
+
+
+Config file for *SELL services* authentication
+----------------------------------------------
+
+Config file example `your/path/to/buy_services_prod_config.yml`:
+
+    description: my account for sell services, access to production server  
+
+    services: sell
+
+    client_id: __copy_here_your_blomming_api_client_id__
+    client_secret: __copy_here_your_blomming_api_client_secret__
+
+    username: __copy_here_your_blomming_account_username__
+    password: __copy_here_your_blomming_account_password__
+
+    domain: https://api.blomming.com
+    api_version: /v1
+
+    default_currency: EUR
+    default_locale: it
+
+    verbose: true 
+  
+CONFIGURATION_HELP
+  end
+end

data/lib/blomming_api/oauth_endpoint.rb

@@ -0,0 +1,83 @@
+# encoding: utf-8
+require 'multi_json'
+require 'rest_client'
+
+module BlommingApi
+  module OauthEndpoint
+    #
+    # authentication request
+    # 
+    # => to get initial OAuth access token:
+    # 
+    #        authenticate :initialize
+    #
+    # => to get refresh token in case of OAuth access token expired  
+    # 
+    #        authenticate :refresh
+    #
+    def authenticate(type=:initialize)
+      url = api_url('/oauth/token')
+      services = @services.downcase.to_sym
+
+      # client_id and client_secret are required for any kind of request 
+      auth_params = { client_id: @client_id, client_secret: @client_secret }
+
+      # authentication type must be :initalize or :refresh 
+      if type == :initialize
+
+        # authentication for services :buy or :sell 
+        if services == :buy
+          @grant_type = "client_credentials" 	
+          auth_params.merge! grant_type: @grant_type
+
+        elsif services == :sell
+          @grant_type = "password"	
+          auth_params.merge! \
+            grant_type: @grant_type, username: @username, password: @password
+
+        else
+          raise"FATAL: config value for: services (#@services): invalid"    
+        end
+      
+      elsif type == :refresh
+      	@grant_type = "refresh_token"
+        auth_params.merge! \
+          grant_type: @grant_type, refresh_token: @refresh_token
+      
+      else
+          raise "FATAL: incorrect authentication type (#{type})"    
+      end     
+
+      data = load_or_retry do 
+        RestClient.post url, auth_params
+      end  
+
+      #puts_response_header(__method__, data) if @verbose_access_token
+      #puts_access_token(access_token) if @verbose
+
+      # assign all token info to instance variables
+      @token_type = data["token_type"]
+      @expires_in = data["expires_in"]
+      @refresh_token = data["refresh_token"]
+      @access_token = data["access_token"]
+    end
+    private :authenticate
+
+
+    def show_authentication (config_file)
+      "\tservices: #{@services}\n" +
+      "\tgrant_type: #{@grant_type}\n" +       
+      "\tusername: #{@username}\n" + 
+      "\tpassword: #{@password}\n" + 
+      "\tclient_id: #{@client_id}\n" + 
+      "\tclient_secret: #{@client_secret}\n\n" +
+
+      "\ttoken_type: #{@token_type}\n" +
+      "\texpires_in: #{@expires_in}\n" +
+      "\trefresh_token: #{@refresh_token}\n" +
+      "\taccess_token: #{@access_token}\n\n"
+    end
+    public :show_authentication
+
+  end
+end

data/lib/blomming_api/private_helpers.rb

@@ -0,0 +1,78 @@
+# encoding: utf-8
+require 'multi_json'
+
+module BlommingApi
+  module PrivateHelpers
+    #
+    # build complete URL of any API request endpoint URI 
+    #
+    def api_url (api_endpoint_uri) 
+	  "#{@domain}#{@api_version}#{api_endpoint_uri}"
+    end  
+
+  	#
+    # return the hash to be used as HTTP header in all API requests,
+    # embedding authentication token and all optional parameters
+    # 
+    def request_params(params={})
+	  { authorization: "Bearer #{@access_token}", params: params }
+    end
+
+    #
+    # private helper: manage RestClient exceptions. iterator.  
+    #
+    def load_or_retry (retry_seconds=2, &restclient_call_block)
+      begin    
+        json_data = restclient_call_block.call 
+
+        # IP connection error, wrong url, etc.
+        rescue SocketError => e
+          STDERR.puts "#{Time.now}: socket error: #{e}. Possible net connection problems. Retry in #{retry_seconds} seconds."
+          sleep retry_seconds
+          retry
+
+        # restclient exceptions
+        rescue => e
+
+        # 
+        # HTTP status code manager
+        #
+        if 401 == e.response.code
+          # Client authentication failed due to unknown client, no client authentication included, 
+          # or unsupported authentication method
+          # After your bearer token has expired, each request done with that stale token will return an HTTP code 401
+          STDERR.puts "#{Time.now}:  restclient error. http status code: #{e.response.code}: #{e.response.body}. Invalid or expired token. Retry in #{retry_seconds} seconds."
+
+          # opinabile mettere la sleep qui, ma meglio per evitare loop stretto
+          sleep retry_seconds
+
+          # richiede il token daccapo. da rivedere.
+          authenticate :refresh
+          retry
+
+        elsif 404 == e.response.code
+          STDERR.puts "#{Time.now}: restclient error. http status code: #{e.response.code}: #{e.response.body}. Exit."
+          exit
+
+        # Invalid or blank request body given (selll services endpoints)
+        elsif 422 == e.response.code
+          STDERR.puts "#{Time.now}: restclient error. http status code: #{e.response.code}: #{e.response.body}. Exit."
+          exit
+
+        elsif [500, 520].include? e.response.code
+          STDERR.puts "#{Time.now}: restclient error. http status code: #{e.response.code}: #{e.response.body}. Retry in #{retry_seconds} seconds."
+          sleep retry_seconds
+          retry
+
+        else
+          STDERR.puts "#{Time.now}: restclient error. http status code: #{e.response.code}: #{e.response.body}. Exit."
+          exit
+        end
+      end
+
+      # HTTP status 200: return data (json to hash)
+      MultiJson.load json_data
+    end
+
+  end
+end

data/lib/blomming_api/public_helpers.rb

@@ -0,0 +1,93 @@
+# encoding: utf-8
+require 'multi_json'
+require 'rest_client'
+
+module BlommingApi
+  module PublicHelpers
+
+    #
+    # all_pages 
+    # It's a Ruby block iterator that retrieve all items of all pages of any API endpoint.
+    # Usage example:
+    # all_pages { |page, per_page| 
+    #   client.shop_items(shop_id, {:page => page, :per_page => per_page}) 
+    # } 
+    #
+    def all_pages (verbose=:stdout, per_page=16, &endpoint_call_block)
+      page = 1
+      data = []
+
+      unless block_given? 
+        raise 'method require a block! usage: #{__method__} '\
+              '{ |page, per_page| endpoint_method(..., {page: page, per_page: per_page}) }'
+      end  	
+
+      print 'collecting all items from de-pagination ' if verbose==:stdout
+
+      loop do
+        print "." if verbose==:stdout
+
+        # run block passing local variables: page, per_page.  
+        data_single_page = endpoint_call_block.call page, per_page
+
+        # debug
+        # data_single_page.each_with_index { |item, index| 
+        #  puts "#{index+1}: title: #{item["title"]}, id: #{item["id"]}, shop: #{item["shop"]["id"]}" }
+
+        data.concat data_single_page 
+
+        break if (data_single_page.size < per_page) || data_single_page.empty?
+        page += 1
+      end
+
+      print "\n" if verbose==:stdout 
+      data
+    end
+
+    def puts_response_header(method, data)   
+      puts "#{method.to_s} response header_params:"
+      puts data.header_params.to_s  
+      puts
+      puts "#{method.to_s} response data:"
+      puts data
+      puts
+    end
+
+    def dump_pretty (json_data)
+      # JSON.pretty_generate(JSON.parse(json_data))
+      puts MultiJson.dump json_data, :pretty => true 
+    end
+
+
+    #
+    # class methods
+    # 
+
+    #
+    # search in +data+ hash field +name+ and get value of corresponding 'id'
+    # (per endpoint categories, collections) 
+    #
+    def self.id_from_name (name, data)
+      id = nil
+      data.each  { |item|
+        if name == item["name"]
+          # estrae l'id dal campo: items_url.
+          id = item["items_url"].split('/')[-2]   # scan( /\d+/ ).last
+          break
+        end  
+      }
+      id
+    end
+
+    #
+    # collect key values associated to a key in +array+ of hashes
+    # return nil if +array+ doesn't exist
+    # return array containing a values list associated to +key_name+
+    #
+    def self.collect_key_values (array, key_name)
+      return nil if array.nil?
+      return array.collect { |item| item[key_name] }
+    end
+    
+  end
+end  	

data/lib/blomming_api/sell_endpoints.rb

@@ -0,0 +1,300 @@
+# encoding: utf-8
+require 'multi_json'
+require 'rest_client'
+
+module BlommingApi
+  module SellEndpoints
+
+    #
+    # PAYMENT_TYPES
+    #
+    def sell_payment_types_find (params={})
+      url = api_url "/sell/payment_types​/user_list"
+      req = request_params(params)
+
+      load_or_retry do
+        RestClient.get url, req
+      end  
+    end
+
+    def sell_payment_types_create (payload, params={})
+      url = api_url "/sell/payment_types​/new"
+      load = MultiJson.dump payload
+      req = request_params(params)
+
+      load_or_retry do
+        RestClient.post url, load, req 
+      end  
+    end
+
+    def sell_payment_types_update (id, payload, params={})
+      url = api_url "/sell/payment_types​/#{id}"
+      load = MultiJson.dump payload
+      req = request_params(params)
+
+      load_or_retry do
+        RestClient.put url, load, req 
+      end  
+    end
+
+    def sell_payment_types_delete (id, params={})
+      url = api_url "/sell/payment_types​/#{id}"
+      req = request_params(params)
+
+      load_or_retry do
+        RestClient.delete url, req 
+      end  
+    end
+
+    #
+    # REGISTER
+    #
+    def sell_register (payload, params={})
+      url = api_url "/sell/register"
+      load = MultiJson.dump payload
+      req = request_params(params)
+
+      load_or_retry do
+        RestClient.post url, load, req 
+      end  
+    end
+
+    #
+    # SHIPPING_COUNTRIES
+    #
+    def sell_shipping_countries_all (params={})
+      url = api_url "/sell/shipping_countries​​/all"
+      req = request_params({locale: @locale}.merge(params))
+
+      load_or_retry do
+        RestClient.get url, req
+      end  
+    end
+
+    #
+    # SHIPPING_PROFILES
+    #
+ 
+    def sell_shipping_profiles (params={})
+      url = api_url "/sell/shipping_profiles"
+      req = request_params(params)
+
+      load_or_retry do
+        RestClient.get url, req
+      end
+    end
+
+    def sell_shipping_profile_create (payload, params={})
+      url = api_url "/sell/shipping_profiles"
+      load = MultiJson.dump payload
+      req = request_params(params)
+
+      load_or_retry do
+        RestClient.post url, load, req 
+      end  
+    end
+
+=begin
+    def sell_shipping_profile_update (payload, params={})
+      url = api_url "/sell/shipping_profiles"
+      load = MultiJson.dump payload
+      req = request_params(params)
+
+      load_or_retry do
+        RestClient.put url, load, req 
+      end  
+    end
+=end
+
+    def sell_shipping_profile_update (payload, params={})
+      url = api_url "/sell/shipping_profiles/#{id}"
+      load = MultiJson.dump payload
+      req = request_params(params)
+
+      load_or_retry do
+        RestClient.put url, load, req 
+      end  
+    end
+
+    def sell_shipping_profile_delete (id, params={})
+      url = api_url "/sell/payment_types​/#{id}"
+      req = request_params(params)
+
+      load_or_retry do
+        RestClient.delete url, req 
+      end  
+    end
+
+    def sell_shipping_profile_find (id, params={})
+      url = api_url "/sell/payment_types​/#{id}"
+      req = request_params(params)
+
+      load_or_retry do
+        RestClient.get url, req 
+      end  
+    end
+
+    def sell_shipping_profile_item_create (payload, item_id, params={})
+      url = api_url "/sell/shipping_profiles/items​/#{item_id}"
+      load = MultiJson.dump payload
+      req = request_params(params)
+
+      load_or_retry do
+        RestClient.post url, load, req 
+      end  
+    end
+
+
+    #
+    # SHIPPING_REGIONS
+    #
+    def sell_shipping_regions (params={})
+      url = api_url "/sell/shipping_regions​/all"
+      req = request_params({locale: @locale}.merge(params))
+
+      load_or_retry do
+        RestClient.get url, req
+      end  
+    end
+
+    #
+    # SHOP_DASHBOARD
+    #
+    def sell_shop_dashboard (params={})
+      url = api_url "/sell/shop/dashboard"
+      req = request_params({locale: @locale}.merge(params))
+
+      load_or_retry do
+        RestClient.get url, req
+      end  
+    end
+
+    #
+    # SHOP_ITEMS
+    #
+    def sell_shop_items (params={})
+      url = api_url '/sell/shop/items'
+      req = request_params(params)
+
+      load_or_retry do
+        RestClient.get url, req
+      end  
+    end
+
+    def sell_shop_item_create (payload, params={})
+      url = api_url '/sell/shop/items/new'
+      load = MultiJson.dump payload
+      req = request_params(params)
+
+      load_or_retry do
+        RestClient.post url, load, req 
+      end  
+    end
+
+    def sell_shop_item_find (item_id, params={})
+      url = api_url "/sell/shop/items/#{item_id}"
+      req = request_params(params)
+
+      load_or_retry do
+        RestClient.get url, req
+      end  
+    end
+
+    def sell_shop_item_update (item_id, payload, params={})
+      url = api_url "/sell/shop/items/#{item_id}"
+      load = MultiJson.dump payload
+      req = request_params(params)
+
+      load_or_retry do
+        RestClient.put url, load, req
+      end    
+    end
+
+    def sell_shop_item_delete (item_id, params={})
+      url = api_url "/sell/shop/items/#{item_id}"
+      req = request_params(params)
+
+      load_or_retry do
+        RestClient.delete url, req
+      end  
+    end
+
+
+    #
+    # SHOP_ORDERS
+    #
+    def sell_shop_orders_states (params={})
+      url = api_url "/sell/shop/orders/states"
+      req = request_params(params)
+
+      load_or_retry do
+        RestClient.get url, req
+      end  
+    end
+
+    def sell_shop_orders (order_status, params={})
+      url = api_url "/sell/shop/orders"
+      req = request_params({ order_status: order_status, currency: @currency, locale: @locale}.merge(params))
+
+      load_or_retry do
+        RestClient.get url, req
+      end  
+    end
+
+    def sell_shop_orders_order_number (order_number, params={})
+      url = api_url "/sell/shop/orders/#{order_number}"
+      req = request_params(params)
+
+      load_or_retry do
+        RestClient.get url, req
+      end  
+    end
+
+    def sell_shop_orders_order_number_change_state (state, params={})
+      url = api_url "/sell/shop/orders/#{order_number}/change_state"
+      req = request_params({state: state}.merge(params))
+
+      load_or_retry do
+        # POST with a hash sends parameters as a urlencoded form body
+        RestClient.post url, req
+      end  
+    end
+
+
+    def sell_shop_orders_order_number_request_cancellation (reason_string, params={})
+      url = api_url "/sell/shop/orders/#{order_number}/request_cancellation"
+      req = request_params(params)
+      load = MultiJson.dump reason: reason_string
+
+      load_or_retry do
+        # POST with raw payloads
+        RestClient.post url, load, req
+      end  
+    end
+
+    #
+    # SHOP_SHIPPING_PROFILES
+    #
+    def sell_shop_shipping_profiles (params={})
+      url = api_url "/sell/shop/shipping_profiles"
+      req = request_params({locale: @locale}.merge(params))
+
+      load_or_retry do
+        RestClient.get url, req
+      end  
+    end
+
+    #
+    # SHOP_USER_DETAILS
+    #
+    def sell_shop_user_details (params={})
+      url = api_url "/sell/shop/user_details"
+      req = request_params({locale: @locale}.merge(params))
+
+      load_or_retry do
+        RestClient.get url, req
+      end  
+    end
+
+  end
+end

data/lib/blomming_api/version.rb

@@ -0,0 +1,3 @@
+module BlommingApi
+  VERSION = "0.4.1"
+end