collector-ruby 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a3ee1393ab7c170b016813a73ea4762cb136bc60
+  data.tar.gz: c77ea79dba484ad8f9591068000bc68f9580cd34
+SHA512:
+  metadata.gz: bcfff7ccb4d15c5b732285e892a571c169acaa42227755689fa5a599ac464dcfe85c2f0355afab2932136b478e199c27d389c7648b0d6725b3d5e718d22dc397
+  data.tar.gz: bb5039c39b3e83f602fb3a74c89f78c2e9e86f1a0080467f8f86133d8e30d9dd53f077b3321f693dee3d842e439eb205cb7de754f3de4d90ec4486bc04df4155

data/.autotest

@@ -0,0 +1,4 @@
+Autotest.add_hook(:initialize) do |at|
+  %w{.git coverage log fixtures}.each {|exception| at.add_exception(exception)}
+  at.prefix = "bundle exec "
+end

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
+.DS_Store
+fixtures/vcr_cassettes

data/.rspec

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

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+# TODO: Move to .gemspec once Savon 3 is released
+gem 'savon', :github => "savonrb/savon", :branch => "master"
+
+# Specify your gem's dependencies in collector-ruby.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Felix Holmgren
+
+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,170 @@
+# Collector::Ruby
+
+This gem provides an interface to the [Collector SOAP API](https://commerce.collector.se/en/Integration/API/) for payments handling.
+
+__Important__: `collector-ruby` depends on the unfinished version 3 of Savon, and therefore users of this gem must also include this in their Gemfile:
+
+    gem 'savon', :github => "savonrb/savon", :branch => "master"
+
+*NOTE: `collector-ruby` will soon be updated to use Savon's successor.*
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'collector-ruby'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself:
+
+	$ gem install collector-ruby
+	
+
+Inside of your Ruby program, require collector-ruby:
+
+	require 'collector-ruby'
+
+__Important__: See note above about adding Savon to your app's dependencies.
+
+# Usage
+## Initializing the client
+All calls to the Collector API are performed by instances of the `Collector::Client` class. The client has no state apart from the configuration parameters passed when initializing it. The initializer requires the user name and password, and an optional third parameter specifies whether to use the sandbox environment.
+
+	regular_client = Collector.new(user_name, password)
+	sandbox_client = Collector.new(user_name, password, true)
+
+## Errors
+The `Client` object performs basic validation of all requests (checking that all required parameters are present), and raises an `ArgumentError` if the validation fails.
+
+If a call to the Collector API fails, an instance of `CollectorError` will be raised. This class has a property called `faultcode` which contains the error code as it appears in [the Collector documentation](https://commerce.collector.se/en/Integration/API/General/Error-codes/), e.g. `INVALID_REGISTRATION_NUMBER`. The full description returned by Collector is set as the error object's `message`.
+
+For some common Collector API errors, custom error classes are implemented. Currently these errors may be raised.
+
+    InvoiceNotFoundError
+	InvalidInvoiceStatusError
+	InvalidTransactionAmountError
+
+These are subclasses of `CollectorError` and thus also have the `faultcode` property.
+
+## Add Invoice
+
+	require 'collector'
+
+	address = Collector::Address.new(
+	            address1: "GATUADRESSAKT211",
+	            city: "UMEÅ",
+	            country_code: "SE",
+	            postal_code: "90737",
+	            first_name: "FÖRNAMNAKT211",
+	            last_name: "EFTERNAMNAKT211" )
+
+	invoice_row = Collector::InvoiceRow.new(
+	                article_id: 12,
+	                description: "A wonderful thing",
+	                quantity: "2",
+	                unit_price: 12.0,
+	                vat: 2.0 )
+
+	invoice_request = Collector::InvoiceRequest.new(activation_option: 0,
+	                    country_code: "SE",
+	                    currency: "SEK",
+	                    delivery_address: address,
+	                    invoice_address: address,
+	                    invoice_delivery_method: 1,
+	                    invoice_rows: [invoice_row],
+	                    invoice_type: 0,
+	                    order_date: DateTime.now,
+	                    reg_no: "1602079954",
+	                    store_id: "355" )
+
+	user_name = "" # Your Collector user name
+	password = "" # Your Collector password
+
+	collector = Collector.new(user_name, password)
+	response = collector.add_invoice(invoice_request)
+
+	puts "Response: #{response.inspect}"
+	# => <Collector::AddInvoiceResponse:0x007f9c358c13c8 @available_reservation_amount="0", @correlation_id=nil, @due_date=nil, @invoice_no="125434", @invoice_status="1", @invoice_url=nil, @lowest_amount_to_pay=nil, @payment_reference=nil, @total_amount=nil>
+
+## Activate Invoice
+These methods return instances of `Collector::InvoiceResponse`, which has the the following attributes:
+`:available_reservation_amount, :correlation_id,`
+`:due_date, :invoice_no, :invoice_status, :invoice_url,`
+`:lowest_amount_to_pay, :payment_reference, :total_amount,`
+`:new_invoice_no`
+
+(`:new_invoice_no` is only returned when partially activating an invoice.)
+
+
+### Full Activation
+    response = @client.activate_invoice(invoice_no: invoice_no,
+                                            store_id: "355",
+                                            country_code: "SE",
+                                            correlation_id: "optional_unique_string")
+
+
+
+### Part Activation
+Part activation of an invoice can be performed either by calling the same `#activate_invoice` method as for full activation, but including `article_list` among the parameters, or more explicitly by calling `#part_activate_invoice`.
+
+Whichever method is used, the same parameters are expected and the response is identical. The only difference is that when `#part_activate_invoice` is called without an `article_list` parameter, an `ArgumentError` will be raised.
+
+    item = Collector::ArticleListItem.new(article_id: 101, quantity: 1, description: "A fine piece")
+    item2 = Collector::ArticleListItem.new(article_id: 102, quantity: 1, description: "Another fine piece")
+    response = @client.part_activate_invoice(
+                    invoice_no: invoice_no,
+                      store_id: "355",
+                  country_code: "SE",
+                  article_list: [item, item2])
+
+`ArticleListItem` instances can also be initialized from `InvoiceRow` objects:
+
+    item = Collector::ArticleListItem.new(invoice_row)
+
+## Replace Invoice
+
+Also returns an instance of `Collector::InvoiceResponse`, but with values for only the following fields: `CorrelationId`, `AvailableReservationAmount`, `TotalAmount`, `InvoiceStatus`. This operation does **not** create a new invoice number.
+
+	new_invoice_row = Collector::InvoiceRow.new(
+		                article_id: 123,
+		                description: "A new shiny gadget",
+		                quantity: "2",
+		                unit_price: 250.0,
+		                vat: 2.0)
+	response = @client.replace_invoice(invoice_no: invoice_no,
+	                                     store_id: "355",
+	                                 country_code: "SE",
+	                               correlation_id: "testing_replace_invoice",
+	                                 invoice_rows: [new_row])
+
+## Adjust Invoice
+
+    correlation_id = @client.adjust_invoice(invoice_no: invoice_no,
+                           article_id: 101,
+                          description: "You are our 100th customer!",
+                               amount: "-20.0",
+                                  vat: "2.0",
+                             store_id: "355",
+                         country_code: "SE",
+                       correlation_id: "optional_unique_string")
+The same invoice can be adjusted to a lower amount several times, and may also be adjusted by a positive amount, but only up to the original amount of the invoice. If an attempt is made to adjust the invoice beyond its original amount, an `InvalidTransactionAmountError` will be raised.
+
+## Cancel Invoice
+    correlation_id = @client.cancel_invoice(invoice_no: invoice_no,
+                             store_id: "355",
+                         country_code: "SE",
+                       correlation_id: "optional_unique_string" )
+
+Attempts to cancel an already canceled invoice will result in an `InvalidInvoiceStatusError`.
+
+## Get Address
+    user = @client.get_address(reg_no: "1602079954", store_id: "355")
+
+The returned `User` object has the following attributes:
+
+    :first_name, :last_name, :reg_no, :addresses
+
+`addresses` is an array, but currently contains at most one address. This operation is only available in Sweden, and an agreement with Collector is required for its use.

data/Rakefile

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

data/collector-ruby.gemspec

@@ -0,0 +1,33 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'collector/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "collector-ruby"
+  spec.version       = Collector::VERSION
+  spec.authors       = ["Felix Holmgren"]
+  spec.email         = ["felix.holmgren@gmail.com"]
+  spec.description   = %q{Client for the Collector API}
+  spec.summary       = %q{Just starting out}
+  spec.homepage      = ""
+  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_runtime_dependency "virtus", ">= 0.5.0"
+  spec.add_runtime_dependency "representable"
+  spec.add_runtime_dependency "activesupport"
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "~> 2.13"
+  spec.add_development_dependency "require_all"
+  spec.add_development_dependency "webmock"
+  spec.add_development_dependency "vcr"
+  spec.add_development_dependency 'commander'
+  spec.add_development_dependency 'terminal-table'
+end

data/collector_browser.rb

@@ -0,0 +1,93 @@
+require 'commander/import'
+
+program :version, '0.0.1'
+program :name, 'Collector browser'
+program :description, 'Simple tool to browse the Collector API.'
+
+require 'savon'
+require 'terminal-table'
+
+CollectorUrl = 'https://eCommerceTest.collector.se/v3.0/InvoiceServiceV31.svc?wsdl'
+ServiceName =  :InvoiceServiceV31
+PortName =     :BasicHttpBinding_IInvoiceServiceV31
+
+default_command :menu
+
+def client
+  return @savon if @savon
+  http = Savon::HTTPClient.new
+  http.client.ssl_config.ssl_version = 'TLSv1'
+  @savon = Savon.new(CollectorUrl, http)
+end
+
+def operations
+  @operations ||= client.operations(ServiceName, PortName)
+end
+
+def build_operation_info(parts)
+  memo = {}
+
+  parts.each do |element|
+    name = element.name.to_sym
+
+    case
+    when element.simple_type?
+      base_type_local = element.base_type.split(':').last
+      memo[name] = {type: base_type_local, simple: true, singular: element.singular?}
+
+    when element.complex_type?
+      value = build_operation_info(element.children)
+      memo[name] = {type: :complex, sub_part: value, simple: false, singular: element.singular?}
+    end
+  end
+
+  memo
+end
+
+def clear_screen
+  system ("clear")
+end
+
+def print_example(operation_name, path = [0])
+  clear_screen
+  operation = client.wsdl.operation(ServiceName.to_s, PortName.to_s, operation_name.to_s)
+  info = build_operation_info operation.input.body_parts
+  request_name = info.keys.first
+  hash = info
+  path.each{|index| key = hash.keys[index] ; hash = hash[key][:sub_part] }
+  rows = hash.keys.map.each_with_index do |key, idx|
+    value = hash[key]
+    [value[:simple] ? "-" : idx + 1,
+      key,
+      value[:type],
+      value[:singular]]
+  end
+  puts Terminal::Table.new :title => request_name, :headings => ['#', 'Param', 'Type', 'Singular?'], rows: rows
+  choice = ask("Choose nested structure, (b)ack, or e(x)it")
+  case choice
+  when "x"
+    abort
+  when "b"
+    if path.count == 1
+      print_menu
+    else
+      path.pop
+      print_example(operation_name, path)
+    end
+  else
+    print_example(operation_name, path << (choice.to_i - 1))
+  end
+end
+
+def print_menu
+  clear_screen
+  rows = operations.map.each_with_index{|name, idx| [idx + 1, name] }
+  table = Terminal::Table.new :title => "Operations", :headings => ['#', 'Operation'], rows: rows
+  puts table
+  choice = ask("Operation?")
+  print_example(operations[choice.to_i - 1])
+end
+
+command :menu do
+  print_menu
+end

data/lib/collector.rb

@@ -0,0 +1,25 @@
+require "collector/version"
+require "collector/base_model"
+require "collector/client"
+require "collector/address"
+require "collector/user"
+require "collector/invoice_row"
+require "collector/article_list_item"
+
+require "collector/invoice_request"
+require "collector/cancel_invoice_request"
+require "collector/adjust_invoice_request"
+require "collector/replace_invoice_request"
+require "collector/activate_invoice_request"
+require "collector/get_address_request"
+require "collector/invoice_response"
+
+module Collector
+
+  class << self
+    def new(*options)
+      Client.new(*options)
+    end
+  end
+
+end

data/lib/collector/activate_invoice_request.rb

@@ -0,0 +1,45 @@
+require 'representable/hash'
+require 'representable/hash/collection'
+
+module Collector
+  class ActivateInvoiceRequest < BaseModel
+
+    attributes :invoice_no, :country_code, :store_id
+    attributes_opt :correlation_id, :article_list
+  end
+
+  class ActivateInvoiceRequestRepresenter < Representable::Decorator
+    include Representable::Hash
+
+    self.representation_wrap = "ActivateInvoiceRequest"
+
+    property   :correlation_id,           as: "CorrelationId"
+    property   :country_code,             as: "CountryCode"
+    property   :invoice_no,               as: "InvoiceNo"
+    property   :store_id,                 as: "StoreId"
+  end
+
+  class ArticleListRepresenter < Representable::Decorator
+    include Representable::Hash::Collection
+    self.representation_wrap = "Article"
+    items extend: ArticleListItemRepresenter, class: ArticleListItem
+  end
+
+  # TODO: Figure out how to make subclassing work
+  class PartActivateInvoiceRequestRepresenter < Representable::Decorator
+    include Representable::Hash
+
+    self.representation_wrap = "PartActivateInvoiceRequest"
+
+    property   :article_list,
+                  writer: lambda {|doc, args|
+                    doc["ArticleList"] = ArticleListRepresenter.new(article_list).to_hash
+                  }
+
+    property   :correlation_id,           as: "CorrelationId"
+    property   :country_code,             as: "CountryCode"
+    property   :invoice_no,               as: "InvoiceNo"
+    property   :store_id,                 as: "StoreId"
+  end
+
+end