nne_client 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
+.rvmrc
+.rspec

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Jacob Atzen
+
+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,92 @@
+# NNEClient
+
+Client library for interacting with the "Navne & Numre Erhverv" SOAP API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'nne_client'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install nne_client
+
+## Warning
+
+NNEClient only works with the Net/HTTP and will force HTTPI to use this.
+
+## Usage
+
+If you need to provide an access key configure NNE Client with:
+
+    NNEClient.configure do |config|
+      config.access_key = 'some key'
+    end
+
+Searching for a company:
+
+    result_set = NNEClient.search(:name => 'Lokalebasen')
+    result_set.first.official_name
+      => "Lokalebasen.dk A/S"
+
+So far the following keys can be used for searching:
+
+    :houseNo (string)
+    :name (string)
+    :nameStartsWith (boolean)
+    :street (string)
+    :zipCode (number)
+    :tdcId (number)
+
+Each entry in the result\_set has the following methods available for accessing
+information about the company:
+
+    ad_protection
+    cvr_no
+    district
+    email
+    founded_year
+    homepage
+    number_of_employees
+    official_name
+    p_no
+    phone
+    status_text
+    street
+    tdf_name
+    zip_code
+
+Additionally further information can be fetched through the methods:
+
+    additional_names
+    trades
+    associates
+    ownerships
+    subsidiaries
+    finances
+
+## Configuration
+
+NNEClient is based on Savon and HTTPI. You may use these libraries to control
+logging. For example:
+
+    HTTPI.log = false
+
+    Savon.configure do |config|
+      config.log = false            # disable logging
+      config.log_level = :info      # changing the log level
+      config.logger = Rails.logger  # using the Rails logger
+    end
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/lib/nne_client/fetch.rb

@@ -0,0 +1,22 @@
+module NNEClient
+  # @!visibility private
+  class Fetch
+    def initialize(tdc_id, command)
+      @tdc_id = tdc_id
+      @command = command
+    end
+
+    def result_set
+      Request.execute(@command) do |xml|
+        tag(xml, :int_1, @tdc_id, :int)
+        tag(xml, :int_2, 0, :int)
+        tag(xml, :String_3, nil, :string)
+        tag(xml, :String_4, NNEClient.config.access_key, :string)
+      end
+    end
+
+    def tag(xml, attribute, value, type)
+      xml.tag!(attribute, value, 'xsi:type' => "xsd:#{type}")
+    end
+  end
+end

data/lib/nne_client/query.rb

@@ -0,0 +1,35 @@
+module NNEClient
+  # @!visibility private
+  class Query
+    def initialize(query_hash, xml)
+      @query_hash = query_hash
+      @xml = xml
+    end
+
+    def render
+      Question.new(@query_hash, @xml).render
+      tag(:int_2, hits_per_page, :int)
+      tag(:int_3, wanted_page_number, :int)
+      tag(:int_4, include_ad_protected, :int)
+      tag(:String_5, NNEClient.config.access_key, :string)
+    end
+
+    private
+
+    def include_ad_protected
+      @query_hash[:include_ad_protected] ? 1 : 0
+    end
+
+    def hits_per_page
+      @query_hash[:hits_per_page] || 10
+    end
+
+    def wanted_page_number
+      @query_hash[:wanted_page_number] || 1
+    end
+
+    def tag(attribute, value, type)
+      @xml.tag!(attribute, value, 'xsi:type' => "xsd:#{type}")
+    end
+  end
+end

data/lib/nne_client/question.rb

@@ -0,0 +1,36 @@
+module NNEClient
+  # @!visibility private
+  class Question
+    def initialize(query_hash, xml)
+      @query_hash = query_hash
+      @xml = xml
+    end
+
+    def render
+      @xml.Question_1(question_attributes) do
+        query(:houseNo, :string)
+        query(:name, :string)
+        query(:nameStartsWith, :boolean)
+        query(:street, :string)
+        query(:zipCode, :int)
+        query(:tdcId, :int)
+      end
+    end
+
+    private
+
+    def query(attribute, type)
+      if @query_hash[attribute]
+        @xml.tag!(attribute, @query_hash[attribute], 'xsi:type' => "xsd:#{type}")
+      end
+    end
+
+    def question_attributes
+      {
+        'xmlns:nne' => "http://com.stibo.net/nne/3.1/Types/NNE",
+        'xsi:type' => "nne:Question"
+      }
+    end
+
+  end
+end

data/lib/nne_client/record_types/finance.rb

@@ -0,0 +1,43 @@
+module NNEClient
+  class Finance
+    extend NNEClient::ResultAttributes
+
+    def initialize(finance_hash)
+      @hash = finance_hash
+    end
+
+    attributes :accounting_date,
+               :assets,
+               :available_funds,
+               :available_funds_ratio,
+               :balance,
+               :capacity_ratio,
+               :contribution_ratio,
+               :credit_rating,
+               :current_assets,
+               :depreciations,
+               :fixed_assets,
+               :fixed_cost,
+               :gross_profit,
+               :income_before_income_tax,
+               :link_pdf,
+               :long_termed_liability,
+               :lots_and_sites,
+               :net_outcome,
+               :number_of_employees,
+               :placings,
+               :profit,
+               :profit_for_the_year,
+               :profit_ratio,
+               :published_date,
+               :return_on_assets,
+               :share_holders_funds_of_interest,
+               :shareholders_funds,
+               :short_termed_liability,
+               :solvency_ratio,
+               :stock,
+               :trade_debitors,
+               :turnover,
+               :year
+  end
+end

data/lib/nne_client/record_types/ownership.rb

@@ -0,0 +1,25 @@
+module NNEClient
+  class Ownership
+    extend NNEClient::ResultAttributes
+
+    attributes :name, :country
+
+    def initialize(ownership_hash)
+      @hash = ownership_hash
+    end
+
+    def share
+      @hash[:share].strip
+    end
+
+    def ==(other)
+      share == other.share &&
+        name == other.name &&
+        country == other.country
+    end
+
+    def company
+      Result.new(:tdc_id => @hash[:tdc_id])
+    end
+  end
+end

data/lib/nne_client/record_types/subsidiary.rb

@@ -0,0 +1,25 @@
+module NNEClient
+  class Subsidiary
+    extend NNEClient::ResultAttributes
+
+    attributes :name, :country
+
+    def initialize(subsidiary_hash)
+      @hash = subsidiary_hash
+    end
+
+    def ==(other)
+      share == other.share &&
+        name == other.name &&
+        country == other.country
+    end
+
+    def share
+      @hash[:share].strip
+    end
+
+    def company
+      Result.new(:tdc_id => @hash[:tdc_id])
+    end
+  end
+end

data/lib/nne_client/record_types/trade.rb

@@ -0,0 +1,21 @@
+module NNEClient
+  class Trade
+    attr_reader :trade_code, :trade
+
+    def initialize(trade_hash)
+      @primary = trade_hash[:primary]
+      @trade_code = trade_hash[:trade_code]
+      @trade = trade_hash[:trade]
+    end
+
+    def primary?
+      @primary
+    end
+
+    def ==(other)
+      primary? == other.primary? &&
+        trade_code == other.trade_code &&
+        trade == other.trade
+    end
+  end
+end

data/lib/nne_client/request.rb

@@ -0,0 +1,56 @@
+module NNEClient
+  # @!visibility private
+  class Request
+    class << self
+      def execute(command, &block)
+        new(command).result_set(&block)
+      end
+    end
+
+    def initialize(command)
+      @command = command
+    end
+
+    def result_set(&block)
+      retries = 3
+      begin
+        ResultSet.new(perform_request(&block))
+      rescue Net::HTTPRequestTimeOut => e
+        retries -= 1
+        retry if retries > 0
+      end
+    end
+
+    private
+
+    def perform_request(&block)
+      client.request('wsdl', @command, request_attributes) do
+        if false
+          # Savon 0.9.5 does not support this
+          soap.body do |xml|
+            yield xml
+          end
+        else
+          # So create a builder manually
+          str = StringIO.new
+          builder = Builder::XmlMarkup.new(:target => str)
+          yield builder
+          str.rewind
+          soap.body = str.read
+        end
+      end
+    end
+
+    def request_attributes
+      { "env:encodingStyle" => "http://schemas.xmlsoap.org/soap/encoding/" }
+    end
+
+    def wsdl_url
+      'http://service.nnerhverv.dk/nne-ws/3.1/NNE?WSDL'
+    end
+
+    def client
+      @client ||= Savon::Client.new(wsdl_url)
+    end
+  end
+end

data/lib/nne_client/result.rb

@@ -0,0 +1,171 @@
+module NNEClient
+
+  # The Result is used to represent a single result from a result set. It can
+  # be seen roughly as an NNE CompanyBasic object. It provides transparent
+  # loading of attributes from the NNE Company object. It also provides methods
+  # for navigating the API further.
+  #
+  # The Result can be instantiated with either a full result hash from an API
+  # query or with just a tdc_id in which case the attributes will be lazy loaded
+  # from the API.
+  class Result
+    class << self
+      # Basic attributes are attributes returned by NNE on the
+      # CompanyBasic object
+      #
+      # @!visibility private
+      def basic_attributes(*attrs)
+        attrs.each do |attr|
+          define_method(attr) { basic_attribute(attr) }
+        end
+      end
+
+      # Extended attributes are attributes returned by NNE on the
+      # Company object
+      #
+      # @!visibility private
+      def extended_attributes(*attrs)
+        attrs.each do |attr|
+          define_method(attr) { extended_attributes[attr] }
+        end
+      end
+    end
+
+    # @!visibility private
+    attr_reader :tdc_id
+
+    # @!visibility private
+    def initialize(result_hash)
+      @basic_attributes = result_hash
+      @tdc_id = result_hash[:tdc_id]
+    end
+
+    # @!attribute [r] cvr_no
+    # @!attribute [r] p_no
+    # @!attribute [r] district
+    # @!attribute [r] phone
+    # @!attribute [r] street
+    # @!attribute [r] zip_code
+    # @!attribute [r] official_name
+    # @!attribute [r] ad_protection
+    basic_attributes :cvr_no, :p_no, :district, :phone, :street, :zip_code,
+                     :official_name, :ad_protection
+
+    # @!attribute [r] email
+    # @!attribute [r] homepage
+    # @!attribute [r] founded_year
+    # @!attribute [r] number_of_employees
+    # @!attribute [r] tdf_name
+    # @!attribute [r] status_text
+    extended_attributes :email, :homepage, :founded_year,
+                        :number_of_employees, :tdf_name, :status_text
+
+    # List of additional_names
+    def additional_names
+      result = Fetch.new(tdc_id, 'fetchCompanyAdditionalNames').result_set.to_hash
+      Array(result[:array_ofstring][:item])
+    end
+
+    # List of trades
+    def trades
+      trades = Fetch.new(tdc_id, 'fetchCompanyTrade').result_set.to_hash[:trade]
+      if trades.kind_of?(Hash)
+        [Trade.new(trades)]
+      else
+        trades.map{|trade| Trade.new(trade) }
+      end
+    end
+
+    # List of associates
+    def associates
+      subsidiaries = fetch_associates
+      if subsidiaries.kind_of?(Hash)
+        [Subsidiary.new(subsidiaries)]
+      else
+        subsidiaries.map{|subsidiary| Subsidiary.new(subsidiary) }
+      end
+    end
+
+    # List of ownerships
+    def ownerships
+      ownerships = fetch_ownerships
+      if ownerships.kind_of?(Hash)
+        [Ownership.new(ownerships)]
+      else
+        ownerships.map{|ownership| Ownership.new(ownership) }
+      end
+    end
+
+    # List of subsidiaries
+    def subsidiaries
+      subsidiaries = fetch_subsidiaries
+      if subsidiaries.kind_of?(Hash)
+        [Subsidiary.new(subsidiaries)]
+      else
+        subsidiaries.map{|subsidiary| Subsidiary.new(subsidiary) }
+      end
+    end
+
+    # List of finance records
+    def finances
+      finances = fetch_finances
+      if finances.kind_of?(Hash)
+        [Finance.new(finances)]
+      else
+        finances.map{|finance| Finance.new(finance) }
+      end
+    end
+
+    def ==(other)
+      other.tdc_id == tdc_id
+    end
+
+    def hash
+      tdc_id.hash
+    end
+
+    def eql?(other)
+      hash == other.hash
+    end
+
+    private
+
+    def fetch_associates
+      Fetch.new(tdc_id, 'fetchCompanyAssociates').result_set.to_hash[:subsidiary] || []
+    end
+
+    def fetch_finances
+      Fetch.new(tdc_id, 'fetchCompanyFinance').result_set.to_hash[:finance] || []
+    end
+
+    def fetch_subsidiaries
+      Fetch.new(tdc_id, 'fetchCompanySubsidiaries').result_set.to_hash[:subsidiary] || []
+    end
+
+    def fetch_ownerships
+      Fetch.new(tdc_id, 'fetchCompanyOwnership').result_set.to_hash[:ownership] || []
+    end
+
+    def basic_attribute(attribute)
+      unless @basic_attributes.has_key?(attribute)
+        unless @basic_result
+          @basic_result = Search.new(:tdcId => tdc_id).result_set.first or
+            raise NNEClient::CompanyMissing
+        end
+        @basic_attributes[attribute] = @basic_result.send(attribute)
+      end
+      return nil if @basic_attributes[attribute].kind_of?(Hash)
+      @basic_attributes[attribute]
+    end
+
+    def extended_attributes
+      @extended_attributes ||= fetch_extended_attributes.reject{ |k,v|
+        v.kind_of?(Hash)
+      }
+    end
+
+    def fetch_extended_attributes
+      Fetch.new(tdc_id, 'fetchCompany').result_set.to_hash[:company]
+    end
+  end
+end

data/lib/nne_client/result_attributes.rb

@@ -0,0 +1,37 @@
+module NNEClient
+
+  # ResultAttributes provides an attributes class method. When calling attributes
+  # with a list of keys from the @hash instance variable a method are defined for
+  # each key returning the value from the @hash. As such it requires a @hash
+  # instance variable on the class that extends the module. Additionally it
+  # ignores any value in the @hash that is itself a Hash. This is due to the way
+  # the NNE SOAP API works together with Savon.
+  #
+  # Example:
+  #
+  #   class Foo
+  #     extends NNEClient::ResultAttributes
+  #     def initialize
+  #       @hash = { :foo => 1, :bar => { :a => 2 }}
+  #       attributes :foo, :bar
+  #     end
+  #   end
+  #
+  #   Foo.new.foo
+  #     => 1
+  #   Foo.new.bar
+  #     => nil
+  #
+  # @!visibility private
+  module ResultAttributes
+
+    # Create a method for each key listed in attrs
+    def attributes(*attrs)
+      attrs.each do |attribute|
+        define_method(attribute) do
+          @hash[attribute] unless @hash[attribute].kind_of?(Hash)
+        end
+      end
+    end
+  end
+end

data/lib/nne_client/result_set.rb

@@ -0,0 +1,43 @@
+module NNEClient
+  # A ResultSet holds the results returned by the SOAP API. The ResultSet includes Enumerable
+  # so it is possible to use all the regular enumerable methods to iterate over it.
+  class ResultSet
+    include Enumerable
+
+    def initialize(result)
+      @result = result
+    end
+
+    # Yield each result in turn
+    def each
+      company_basic.each do |cb|
+        yield Result.new(cb)
+      end
+    end
+
+    # The to_hash method is used by other parts of the library and can't be
+    # made private for now.
+    # @!visibility private
+    def to_hash
+      @result.to_hash
+    end
+
+    def total
+      window[:total].to_i
+    end
+
+    private
+
+    def window
+      to_hash[:window]
+    end
+
+    def company_basic
+      if to_hash[:company_basic].kind_of?(Hash)
+        [to_hash[:company_basic]]
+      else
+        to_hash[:company_basic] || []
+      end
+    end
+  end
+end

data/lib/nne_client/search.rb

@@ -0,0 +1,15 @@
+module NNEClient
+  # @!visibility private
+  class Search
+
+    def initialize(query)
+      @query = query
+    end
+
+    def result_set
+      Request.execute('search') do |xml|
+        Query.new(@query, xml).render
+      end
+    end
+  end
+end

data/lib/nne_client/version.rb

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