tam 1.0.0

data/.gitignore

@@ -0,0 +1,3 @@
+pkg
+Gemfile.lock
+

data/Gemfile

@@ -0,0 +1,3 @@
+source 'http://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Nokia Siemens Networks
+
+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.mkd

@@ -0,0 +1,58 @@
+The telco asset marketplace Ruby gem
+====================================
+A Ruby wrapper for the Telco Asset Marketplace REST APIs
+
+Installation
+------------
+	gem install tam
+	
+Documentation
+-------------
+<https://code.telcoassetmarketplace.com>
+
+How to Use
+----------
+If you are using rails then:
+
+1. Add the tam gem to your Gemfile
+
+```ruby
+	gem 'tam'
+```
+
+2. Create a tam.yml file in config with following contents:
+
+```yaml
+	development: &defaults
+		consumer_key:     # the consumer key generated in telcoassetmarketplace.com for you application
+		consumer_secret:  # the consumer secret generated in telcoassetmarketplace.com for you application
+		consumer_handler: # the of the class that implements the telcoassetmarketplace handler logic
+	test:
+		<<: *defaults
+	production:
+		<<: *defaults
+```
+		
+3. Add following route to your routes.rb
+
+```ruby
+	match '/tamapi/(:string)' => TAM::API 	# you can replace 'tamapi' with any other namespace
+```
+	
+4. Implement the telcoassetmarketplace handler logic (e.g.: tam_handler.rb in helpers)
+
+```ruby
+	class TamHandler
+	  def authorized(user, session)
+		# should return the URL to which telcoassermarketplace should redirect
+	  end
+
+	  def denied(session)
+		# should return the URL to which telcoassermarketplace should redirect
+	  end
+	
+	  def receive_sms(from_user, to_app, body)
+	  end
+	  
+	end
+```	

data/Rakefile

@@ -0,0 +1,31 @@
+begin
+  require "bundler"
+  Bundler.setup
+rescue LoadError
+  $stderr.puts "You need to have Bundler installed to be able build this gem."
+end
+
+gemspec = eval(File.read(Dir["*.gemspec"].first))
+
+
+desc "Validate the gemspec"
+task :gemspec do
+  gemspec.validate
+end
+
+desc "Build gem locally"
+task :build => :gemspec do
+  system "gem build #{gemspec.name}.gemspec"
+  FileUtils.mkdir_p "pkg"
+  FileUtils.mv "#{gemspec.name}-#{gemspec.version}.gem", "pkg"
+end
+
+desc "Install gem locally"
+task :install => :build do
+  system "gem install pkg/#{gemspec.name}-#{gemspec.version}"
+end
+
+desc "Clean automatically generated files"
+task :clean do
+  FileUtils.rm_rf "pkg"
+end

data/lib/tam/api/location.rb

@@ -0,0 +1,26 @@
+require 'json'
+require 'tam/user'
+require 'tam/error'
+
+# SMS part of the telco asset marketplace REST API
+module TAM
+  class API
+    # Find the location (coordinates) of a user
+    #
+    # @return [Hash] 
+    #   {"body"=>
+    #    {"latitude"=>51.618,
+    #     "timestamp"=>1302185772456,
+    #     "accuracy"=>100,
+    #     "longitude"=>23.9063},
+    #   "status"=>{"code"=>0, "message"=>"Request was handled succesfully"}}
+    def self.getcoord(user)
+      begin
+        response = dispatch_to_tam(:get, '/api/1/location/getcoord', user)
+        JSON.parse response
+      rescue TAM::ServiceUnavailable
+        raise TAM::ServiceUnavailable.new 'The location service is not available. If you are using the service on a persona, i.e.: through the sandbox, then remember to set the location of the persona'
+      end
+    end
+  end
+end

data/lib/tam/api/oauth.rb

@@ -0,0 +1,55 @@
+require 'sinatra'
+require 'oauth'
+require 'tam/error'
+require 'tam/user'
+
+# OAUTH part of the telco asset marketplace REST API
+module TAM
+  class API
+    enable :sessions
+    
+    # Authorizes a user of telco asset marketplace to use your application
+    # After the OAUTH flow is finished then the configured consumer_handler.authorized(user, session)
+    # or consumer_handler.denied(session) are invoked
+    get '/*/authorize' do
+      consumer = TAM::API.create_oauth_consumer
+      request_token = consumer.get_request_token
+      session[:request_token] = request_token
+      
+      oauth_callback_url = url('/' + TAM.callback_path + '/oauth_callback')
+      redirect request_token.authorize_url(:oauth_callback => oauth_callback_url)
+    end
+    
+    # OAUTH callback for telco asset marketplace
+    # @private
+    get '/*/oauth_callback' do
+      if params[:denied].nil?
+        consumer = TAM::API.create_oauth_consumer
+        request_token = session[:request_token]
+        verifier = params[:oauth_verifier]
+        access_token = request_token.get_access_token(:oauth_verifier => verifier)
+        user = User.new(access_token.token, access_token.secret)
+        redirect dispatch_to_handler('authorized', user, session)
+      else
+        redirect dispatch_to_handler('denied', session)
+      end
+    end
+    
+    private
+    def self.create_oauth_consumer
+      if TAM.consumer_key.nil? or TAM.consumer_secret.nil?
+        raise OAuthConsumerAttributesMissing.new
+      end
+      
+      OAuth::Consumer.new(TAM.consumer_key, TAM.consumer_secret,
+        {
+          :site => TAM.site,
+          :request_token_path => TAM.request_token_path,
+          :access_token_path => TAM.access_token_path,  
+          :authorize_path => TAM.authorize_path, 
+          :scheme => TAM.oauth_scheme,
+          :http_method => TAM.oauth_http_method
+        })
+    end
+  end
+end

data/lib/tam/api/sms.rb

@@ -0,0 +1,41 @@
+require 'sinatra'
+require 'oauth'
+require 'json'
+require 'tam/user'
+
+# SMS part of the telco asset marketplace REST API
+module TAM
+  class API
+    # URL handler for receiving SMS
+    # After receiving an SMS, the configured 
+    # consumer_handler.receive_sms(from_user, to_app, body)
+    # is invoked
+    #
+    # @private
+    post "/*/receive_sms" do
+      request.body.rewind # in case someone already read it
+      
+      data = JSON.parse request.body.read
+
+      access_token = data["access_token"]
+      token_secret = data["token_secret"]
+      from_user = User.new(access_token, token_secret)
+      to_app = data["to"]
+      body = data["body"]
+      begin
+        dispatch_to_handler('receive_sms', from_user, to_app, body)
+        response.status = 200
+        return ''
+      rescue Error => error
+        response.status = 500
+        return error.message
+      end
+    end
+    
+    # Sends an SMS
+    def self.send_sms(from_app, to_user, body)
+      payload = JSON.generate({'body' => body, 'from' => from_app})
+      dispatch_to_tam(:post, '/api/1/sms/send', to_user, payload)
+    end
+  end
+end

data/lib/tam/api.rb

@@ -0,0 +1,73 @@
+require 'sinatra'
+require 'oauth'
+require 'tam/error'
+require 'tam/user'
+
+module TAM
+  # Wrapper for the telco asset marketplace REST API
+  #
+  # @note All methods have been separated into modules and follow the same grouping used in {https://code.telcoassetmarketplace.com the telco asset marketplace API Documentation}.
+  # @see http://code.telcoassetmarketplace.com
+  class API < Sinatra::Base
+    # Require api method modules after initializing the API class in
+    # order to avoid a superclass mismatch error, allowing those modules to be
+    # API-namespaced.
+    require 'tam/api/oauth'
+    require 'tam/api/sms'
+    require 'tam/api/location'
+    
+    # Dispatches the request to the telco asset marketplace handler configured by 
+    # this gem client
+    def dispatch_to_handler(method, *args)
+      if TAM.consumer_handler.nil?
+        LOGGER.error 'Application has not configured the telco asset marketplace consumer_handler'
+        raise InvalidConsumerHandler.new 'Application has not configured the telco asset marketplace consumer_handler'
+      end
+      
+      if TAM.consumer_handler.respond_to?(method)
+        begin
+          return TAM.consumer_handler.send(method, *args)
+        rescue TAM::Error => error
+          LOGGER.error 'Application has suffered an internal error: ' + error.message + ', ' + error.body
+          raise error
+        end
+      end
+      
+    end
+    
+    # Dispatches the request to the telco asset marketplace REST API
+    def self.dispatch_to_tam(http_method, endpoint, user, payload='')
+      consumer = create_oauth_consumer
+      access_token = OAuth::AccessToken.new(consumer, user.access_token, user.token_secret)
+
+      if (http_method == :get)
+        response = access_token.send(http_method, endpoint, {'Content-Type' => 'application/json'})
+      else
+        response = access_token.send(http_method, endpoint, payload, {'Content-Type' => 'application/json'})
+      end
+      
+      if response.class == Net::HTTPOK
+        return response.body
+      elsif response.class == Net::HTTPUnauthorized
+        LOGGER.error 'Request not authorized ' + response.message + ', ' + response.body
+        raise RequestNotAuthorized.new(response.message, response.body)
+      elsif response.class == Net::HTTPBadRequest
+        if response.body.include? 'consumer_key_unknown'
+          LOGGER.error 'Configured telco asset marketplace consumer_key is not valid: ' + response.message + ', ' + response.body
+          raise InvalidConsumerKey.new(response.message, response.body)
+        elsif response.body.include? 'signature_invalid'
+          LOGGER.error 'Configured telco asset marketplace consumer_secret is not valid: ' + response.message + ', ' + response.body
+          raise InvalidConsumerSecret.new(response.message, response.body)
+        else
+          raise UnexpectedError.new(response.message, response.body)
+        end
+      elsif response.class == Net::HTTPServiceUnavailable
+        LOGGER.error 'telco asset marketplace service ' + endpoint + ' not available'
+        raise ServiceUnavailable.new(response.message, response.body)
+      else
+        raise UnexpectedError.new(response.message, response.body)
+      end
+    end
+    
+  end
+end

data/lib/tam/configuration.rb

@@ -0,0 +1,83 @@
+module TAM
+  # Defines constants and methods related to configuration
+  module Configuration
+    # An array of valid keys in the options hash when configuring a {TAM::API}
+    VALID_OPTIONS_KEYS = [
+      :consumer_key,
+      :consumer_secret,
+      :consumer_handler,
+      :site,
+      :request_token_path,
+      :access_token_path,
+      :authorize_path,
+      :oauth_scheme,
+      :oauth_http_method,
+      :callback_path].freeze
+
+    # @private
+    attr_accessor *VALID_OPTIONS_KEYS
+      
+    def consumer_handler=(consumer_handler)
+      if consumer_handler.class == String
+        begin
+          @consumer_handler = Object.const_get(consumer_handler).new
+        rescue NameError => error
+          LOGGER.error 'Application has provided an invalid telco asset marketplace consumer_handler: ' + TAM.consumer_handler
+          raise InvalidConsumerHandler.new 'Application has provided an invalid telco asset marketplace consumer_handler: ' + TAM.consumer_handler
+        end
+      else
+        @consumer_handler = consumer_handler
+      end
+    end
+    
+    def consumer_handler
+      @consumer_handler
+    end
+    
+    # When this module is extended, set all configuration options to their default values
+    def self.extended(base)
+      base.reset
+    end
+    
+    # Convenience method to allow configuration options to be set in a block
+    def configure
+      yield self
+    end
+    
+    def configure(config)
+      unless config.empty?
+        self.consumer_key       = config['consumer_key']        if config['consumer_key']
+        self.consumer_secret    = config['consumer_secret']     if config['consumer_secret']
+        self.consumer_handler   = config['consumer_handler']    if config['consumer_handler']
+        self.site               = config['site']                if config['site']
+        self.request_token_path = config['request_token_path']  if config['request_token_path']
+        self.access_token_path  = config['access_token_path']   if config['access_token_path']
+        self.authorize_path     = config['authorize_path']      if config['authorize_path']
+        self.oauth_scheme       = config['oauth_scheme']        if config['oauth_scheme']
+        self.oauth_http_method  = config['oauth_http_method']   if config['oauth_http_method']
+        self.callback_path      = config['callback_path']       if config['callback_path']
+      end
+    end
+    
+    # Create a hash of options and their values
+    def options
+      Hash[VALID_OPTIONS_KEYS.map {|key| [key, send(key)] }]
+    end
+
+    # Reset all configuration options to defaults
+    def reset
+      self.consumer_key       = nil
+      self.consumer_secret    = nil
+      self.consumer_handler   = nil
+      self.site               = 'https://telcoassetmarketplace.com'
+      self.request_token_path = '/api/1/oauth/request_token'
+      self.access_token_path  = '/api/1/oauth/access_token'
+      self.authorize_path     = '/web/authorize'
+      self.oauth_scheme       = :query_string
+      self.oauth_http_method  = :get
+      self.callback_path      = 'tamapi'
+      self
+    end
+  end  
+end
+    

data/lib/tam/error.rb

@@ -0,0 +1,40 @@
+module TAM
+  # Custom error class for rescuing from all telco asset marketplace errors
+  class Error < StandardError
+    attr_reader :body
+
+    def initialize(message, body = '')
+      @body = body
+      super message
+    end
+  end
+  
+  # Raised when client tries to use any of the API methods that require OAUTH
+  # without configuring the consumer_key or consumer_secret
+  class OAuthConsumerAttributesMissing < Error
+    def initialize
+      super 'consumer_key or consumer_secret not configured'
+    end
+  end
+  
+  # Raised when client tries to use any of the API methods without user authorization
+  class RequestNotAuthorized < Error; end  
+
+  # Raised when client performs a wrong OAUTH interaction (this is a super-class)
+  class OAuthError < Error; end
+
+  # Raised when client is using an invalid consumer_key
+  class InvalidConsumerKey < OAuthError; end
+  
+  # Raised when client is using an invalid consumer_secret
+  class InvalidConsumerSecret < OAuthError; end
+  
+  # Raised when client is using an invalid consumer_handler
+  class InvalidConsumerHandler < Error; end
+
+  class UnexpectedError < Error; end  
+  
+  # Raised when one of the telco asset marketplace services is not available
+  class ServiceUnavailable < Error; end
+end
+  

data/lib/tam/railtie.rb

@@ -0,0 +1,30 @@
+require 'rails'
+
+module TAM
+  class TamRailtie < Rails::Railtie
+    initializer "tam.boot" do
+      configure_with_yaml
+    end
+    
+    private
+    
+    # Attempts to load the telco asset marketplace configuration from config/tam.yml
+    # in a rails 3 application.
+    # Besides using a tam.yml, developers can also configure directly TAM settings, e.g.:
+    # TAM.consumer_key = 'h42woy35tl08o44l'
+    def configure_with_yaml
+      cfg = load_config(File.join(Rails.root, 'config', 'tam.yml')).freeze
+      TAM.configure(cfg)
+    end
+    
+    def load_config(yaml_file)
+      return {} unless File.exist?(yaml_file)
+      cfg = YAML::load(File.open(yaml_file))
+      if defined? Rails
+        cfg = cfg[Rails.env]
+      end
+      cfg
+    end
+    
+  end
+end

data/lib/tam/user.rb

@@ -0,0 +1,12 @@
+module TAM
+  # Represents an end-user of telco asset marketplace (a subscriber)
+  class User
+    attr_accessor :access_token
+    attr_accessor :token_secret
+    
+    def initialize(access_token, token_secret)
+      @access_token = access_token
+      @token_secret = token_secret
+    end
+  end
+end

data/lib/tam/version.rb

@@ -0,0 +1,4 @@
+module TAM
+  # The version of the gem
+  VERSION = '1.0.0'.freeze unless defined?(::TAM::VERSION)
+end

data/lib/tam.rb

@@ -0,0 +1,17 @@
+require 'tam/railtie' if defined? ::Rails::Railtie
+require 'tam/configuration'
+require 'tam/api'
+
+module TAM
+  extend Configuration
+
+  # If in rails environment then we use the rails default logger
+  # otherwise we create one that points to the standard output
+  LOGGER = 
+    if defined? Rails 
+      RAILS_DEFAULT_LOGGER
+    else 
+      Logger.new(STDOUT)
+    end
+
+end

data/tam.gemspec

@@ -0,0 +1,38 @@
+# coding: UTF-8
+require File.expand_path('../lib/tam/version', __FILE__)
+
+Gem::Specification.new do |s|
+  s.add_runtime_dependency('sinatra', '~> 1.2.1')
+  s.add_runtime_dependency('json', '~> 1.5')
+  s.add_runtime_dependency('oauth', '~> 0.4.3')
+  
+  s.name = "tam"
+  s.version = TAM::VERSION.dup
+  s.platform = Gem::Platform::RUBY
+  s.authors = ["Carlos Manzanares"]
+  s.email = ["developers@telcoassetmarketplace.com"]
+  s.homepage = "https://github.com/tamdeveloper/telco-asset-marketplace-gem"
+  s.description = %q{The Ruby gem for the telco asset marketplace REST APIs}
+  s.summary = "telco asset marketplace Ruby gem"
+  s.rubyforge_project = s.name
+
+  s.required_rubygems_version = Gem::Requirement.new('>= 1.3.6') if s.respond_to? :required_rubygems_version=
+  
+  s.require_path = 'lib'
+  s.executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.files = `git ls-files`.split("\n")
+  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")  
+
+  s.post_install_message =<<eos
+********************************************************************************
+
+  Visit our community pages for up-to-date information on 
+  telco asset marketplace:
+      https://code.telcoassetmarketplace.com/
+  Notice that in order to use this gem you will also need to register as a 
+  developer in telco asset marketplace:
+      https://telcoassetmarketplace.com
+
+********************************************************************************  
+eos
+end

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification 
+name: tam
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Carlos Manzanares
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-06-06 00:00:00 +03:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: sinatra
+  type: :runtime
+  prerelease: false
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 29
+        segments: 
+        - 1
+        - 2
+        - 1
+        version: 1.2.1
+  requirement: *id001
+- !ruby/object:Gem::Dependency 
+  name: json
+  type: :runtime
+  prerelease: false
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 5
+        segments: 
+        - 1
+        - 5
+        version: "1.5"
+  requirement: *id002
+- !ruby/object:Gem::Dependency 
+  name: oauth
+  type: :runtime
+  prerelease: false
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 9
+        segments: 
+        - 0
+        - 4
+        - 3
+        version: 0.4.3
+  requirement: *id003
+description: The Ruby gem for the telco asset marketplace REST APIs
+email: 
+- developers@telcoassetmarketplace.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- LICENSE
+- README.mkd
+- Rakefile
+- lib/tam.rb
+- lib/tam/api.rb
+- lib/tam/api/location.rb
+- lib/tam/api/oauth.rb
+- lib/tam/api/sms.rb
+- lib/tam/configuration.rb
+- lib/tam/error.rb
+- lib/tam/railtie.rb
+- lib/tam/user.rb
+- lib/tam/version.rb
+- tam.gemspec
+has_rdoc: true
+homepage: https://github.com/tamdeveloper/telco-asset-marketplace-gem
+licenses: []
+
+post_install_message: |
+  ********************************************************************************
+  
+    Visit our community pages for up-to-date information on 
+    telco asset marketplace:
+        https://code.telcoassetmarketplace.com/
+    Notice that in order to use this gem you will also need to register as a 
+    developer in telco asset marketplace:
+        https://telcoassetmarketplace.com
+  
+  ********************************************************************************  
+
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 23
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: tam
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: telco asset marketplace Ruby gem
+test_files: []
+