fex 0.0.1

data/.gitignore

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

data/.rspec

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

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in fex.gemspec
+gemspec

data/MIT-LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 iain
+
+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,161 @@
+# Fex
+
+Small wrapper around Savon for using FedEx Web Services. It will expose you to
+all the nitty gritty details from the FedEx API.
+
+Disadvantages:
+
+* The FedEx API is big and complex
+* It's not easy to get started
+
+Advantages:
+
+* You can do everything that is allowed by the API.
+* The code is really close to the documentation by FedEx.
+
+It's up to you to decide which approach to take. If you don't do many special
+things, a gem like `fedex`, might be a better alternative, because it hides
+most of the complexity. If you find yourself needing a bit more control, you
+can take this gem.
+
+Note: This gem is not complete. It contains the ship service, address
+validation and rate service. The other services FedEx supplies are a somewhat
+different. It shouldn't be too difficult to support them, but I haven't gotten
+around to it.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'fex'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install fex
+
+## Usage
+
+Create a client with your credentials:
+
+``` ruby
+client = Fex.client(
+
+  # required:
+
+  credentials: {
+    key:             "xxx",
+    password:        "xxx",
+    account_number:  "xxx",
+    meter_number:    "xxx",
+  },
+
+  # optional:
+  mode: "test", # or "production"
+
+  # see Savon for more information about these
+  client: {
+    logger:        Rails.logger,
+    log_level:     "info",
+    log:           true,
+    raise_errors:  true
+  }
+)
+```
+
+Create a service:
+
+``` ruby
+service = client.service(:ship)
+
+# see what operations are available:
+service.operations # => [ :process_shipment, .... ]
+```
+
+Perform a request:
+
+``` ruby
+response = service.call(
+
+  # the operation as mentioned earlier
+  :process_shipment,
+
+  # the attributes (after the Version tag)
+  requested_shipment: {
+    ship_timestamp:  Time.now.utc.iso8601(2),
+    dropoff_type:    "REGULAR_PICKUP",
+    service_type:    "PRIORITY_OVERNIGHT",
+    packaging_type:  "YOUR_PACKAGING",
+    # etc ...
+  }
+)
+```
+
+The response has everything Savon offers, plus some methods specific to FedEx.
+
+``` ruby
+# From Savon:
+response.success?
+response.soap_fault?
+all_the_things = response.body
+severity = response.xpath("//Notifications/Severity").inner_text
+severity = response.css("Severity").inner_text
+
+# From Fex:
+response.severity
+response.code
+response.message
+response.image # only for shipments with labels
+```
+
+For examples on how to use this gem, visit the `spec/integration` directory.
+
+## Running gem specs
+
+To run the specs on this project, you can create a file called
+`spec/support/credentials.yml`, and fill it with your own test keys.
+
+``` yaml
+production:
+  :key: "xxx"
+  :password: "xxx"
+  :account_number: "xxx"
+  :meter_number: "xxx"
+
+test:
+  :key: "xxx"
+  :password: "xxx"
+  :account_number: "xxx"
+  :meter_number: "xxx"
+```
+
+You can specify production and/or test. The production keys are used for the
+address validation service, because that doesn't work for me on test.
+
+To use the keys in an integration spec, add `:production_environment` or
+`:test_environment` as group metadata keys, and the methods `credentials` and
+`mode` are made available for you:
+
+``` ruby
+describe "FedEx rate service", :test_environment do
+
+  it "should do something" do
+    client = Fex.client(credentials: credentials, mode: mode)
+    # etc ...
+  end
+
+end
+```
+
+If you don't specify keys, these specs will be skipped.
+
+## 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 @@
+require "bundler/gem_tasks"

data/fex.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'fex/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "fex"
+  gem.version       = Fex::VERSION
+  gem.authors       = ["iain"]
+  gem.email         = ["iain@iain.nl"]
+  gem.description   = %q{Small wrapper around Savon for using FedEx Web Services}
+  gem.summary       = %q{Small wrapper around Savon for using FedEx Web Services}
+  gem.homepage      = "https://github.com/yourkarma/fex"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency 'savon', '~> 2.0'
+  gem.add_development_dependency "rspec"
+  gem.add_development_dependency "pry-nav"
+end

data/lib/fex.rb

@@ -0,0 +1,10 @@
+require "fex/version"
+require "fex/client"
+
+module Fex
+
+  def self.client(options)
+    Client.new(options)
+  end
+
+end

data/lib/fex/client.rb

@@ -0,0 +1,26 @@
+require "yaml"
+require "fex/service_factory"
+
+module Fex
+  class Client
+
+    attr_reader :globals
+
+    def initialize(globals)
+      @globals = globals
+    end
+
+    def service(name, locals = {})
+      config = service_configuration[name]
+      opts = globals.deep_merge(config).deep_merge(locals)
+      ServiceFactory.new(name, opts).service
+    end
+
+    private
+
+    def service_configuration
+      @service_configuration ||= YAML.load_file(File.expand_path("../services.yml", __FILE__))
+    end
+
+  end
+end

data/lib/fex/response.rb

@@ -0,0 +1,28 @@
+require "delegate"
+require "forwardable"
+
+module Fex
+  class Response < SimpleDelegator
+    extend Forwardable
+
+    def_delegators :doc, :css
+
+    def initialize(*)
+      super
+      doc.remove_namespaces!
+    end
+
+    def severity
+      xpath("//Notifications/Severity").inner_text
+    end
+
+    def code
+      xpath("//Notifications/Code").inner_text
+    end
+
+    def message
+      xpath("//Notifications/Message").inner_text
+    end
+
+  end
+end

data/lib/fex/service.rb

@@ -0,0 +1,57 @@
+require "savon"
+require "forwardable"
+require "fex/wsdl"
+
+module Fex
+
+  # This is a wrapper around Savon, with more or less intelligent defaults.
+  class Service
+    extend Forwardable
+
+    def_delegators :client, :operations
+
+    # The name determines the name of the WSDL file located in the wsdl directory in the root of the gem.
+    # The full path will be calculated by the +WSDL+ class.
+    attr_reader :name
+
+    # Defaults are any values that always exist on this service. Examples are
+    # the credentials and the version.
+    attr_reader :defaults
+
+    # The response is the class that will handle building a response. The
+    # default is the generic +Response+ class.
+    attr_reader :response
+
+    def initialize(options)
+      @name           = options.fetch(:name)
+      @client_options = options[:client] || {}
+      @wsdl           = options[:wsdl]
+      @defaults       = options[:defaults] || {}
+      @response       = options.fetch(:response)
+    end
+
+    def wsdl
+      @wsdl || WSDL.new.path_for(name)
+    end
+
+    def client
+      Savon.client(client_options)
+    end
+
+    def call(operation, message, options = {})
+      opts = {message: defaults.deep_merge(message)}.deep_merge(options)
+      savon_response = client.call(operation, opts)
+      response.new(savon_response)
+    end
+
+    def client_options
+      default_options = {
+        wsdl: wsdl,
+        convert_request_keys_to: :camelcase,
+        pretty_print_xml: true
+      }
+      default_options.deep_merge(@client_options)
+    end
+
+  end
+end

data/lib/fex/service_factory.rb

@@ -0,0 +1,69 @@
+require "fex/service"
+require "fex/response"
+require "fex/ship_response"
+
+module Fex
+  class ServiceFactory
+
+    PRODUCTION_ENDPOINT = "https://ws.fedex.com:443/web-services/rate"
+
+    attr_reader :name, :mode, :client_options, :version, :defaults, :wsdl, :response
+
+    # credentials
+    attr_reader :key, :password, :account_number, :meter_number
+
+    def initialize(name, options)
+      @name           = name
+      @mode           = options.fetch(:mode) { "test" }
+      @version        = options.fetch(:version)  {{}}
+      @client_options = options.fetch(:client)   {{}}
+      @defaults       = options.fetch(:defaults) {{}}
+
+      @credentials    = options.fetch(:credentials)
+      @key            = @credentials.fetch(:key)
+      @password       = @credentials.fetch(:password)
+      @account_number = @credentials.fetch(:account_number)
+      @meter_number   = @credentials.fetch(:meter_number)
+
+      @wsdl = options[:wsdl]
+
+      @response = options[:response] || "Response"
+    end
+
+    def service
+      Service.new(
+        name:       name,
+        client:     merged_client_options,
+        wsdl:       wsdl,
+        defaults:   merged_defaults,
+        response:   Fex.const_get(response)
+      )
+    end
+
+    def merged_defaults
+      authentication.deep_merge(version: version).deep_merge(defaults)
+    end
+
+    def authentication
+      {
+        web_authentication_detail: {
+          user_credential: { key: key, password: password }
+        },
+        client_detail: { account_number: account_number, meter_number: meter_number }
+      }
+    end
+
+    def merged_client_options
+      endpoint_options.deep_merge(client_options)
+    end
+
+    def endpoint_options
+      if mode.to_s == "production"
+        { endpoint: PRODUCTION_ENDPOINT }
+      else
+        {}
+      end
+    end
+
+  end
+end

data/lib/fex/services.yml

@@ -0,0 +1,23 @@
+---
+:address_validation:
+  :version:
+    :service_id: aval
+    :major: 2
+    :intermediate: 0
+    :minor: 0
+:rate:
+  :client:
+    :env_namespace: soapenv
+    :namespace_identifier: v13
+  :version:
+    :service_id: crs
+    :major: 13
+    :intermediate: 0
+    :minor: 0
+:ship:
+  :response: "ShipResponse"
+  :version:
+    :service_id: ship
+    :major: 12
+    :intermediate: 1
+    :minor: 0