figa 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0730264f5ad57b4adcf105062fa9aa2396710067
-  data.tar.gz: 882c6230a5d0b42cf50874f78904259f5ba5e820
+  metadata.gz: 6711826553277276616030f1bd03f3661fdb4f2d
+  data.tar.gz: 839c8010b513be67b475ddc66faab9e046d27b60
 SHA512:
-  metadata.gz: ab01ea02cff6dc17a967b4b59e1ee1869b94b419df57ca0fb4090d9df7f3dc787bc66119a62c56726a536e4feec8b956a95388d26591f53345e06685b0ddad19
-  data.tar.gz: 625d7b5399b4cdf8ee8cabac46990ad147532a634ef8773c4f470c82bd1352b1ff79ee3efde46c01a25ba429f0257e750f98b01fc02d0ce5ba679410bbcea655
+  metadata.gz: 7f5710c727d6a221f0d846574ae75d81fe0d51ad8b690480e9c163025b0cf17c61d6bc4c6519158bc1080dae98170555ee33a263bc3696ff4bb0ecc292936750
+  data.tar.gz: 1210ffc9cff8af805336b6ec2be04b2c5e2ab2067a1e9369816ed41b25e5720c9d9f1ac17f3c0d576b12a79188a89f2d4f5590aa531d11bf0b8f26f83eb84585

data/CHANGELOG.md

@@ -2,7 +2,14 @@
 # CHANGELOG.md
 
 
-## sentofu 0.0.1  released 2019-06-13
+## figa 0.1.0  released 2019-06-14
+
+* Refine Figa::Client #map and #search
+* Provide #next for #search results
+* Use API key if provided to Figa::Client.new
+
+
+## figa 0.0.1  released 2019-06-13
 
 * Initial release
 

data/README.md

@@ -1,11 +1,118 @@
 
 # figa
 
+[![Gem Version](https://badge.fury.io/rb/figa.svg)](http://badge.fury.io/rb/figa)
+
 A Ruby library to query [OpenFIGI](https://www.openfigi.com/) API v2.
 
 
 ## usage
 
+Instantiate a Figa client:
+```ruby
+client = Figa::Client.new
+  #
+  # instantiate a client without API key
+
+client = Figa::Client.new('321456cd-af64-9932-bcbe-1a2345677999')
+  #
+  # instantiate a client with an API key
+```
+
+Query for mappings ([/v2/mapping](https://www.openfigi.com/api#post-v2-mapping)):
+```ruby
+client = Figa::Client.new
+
+r = client.map(isin: 'US4592001014')
+
+pp r
+  # ==>
+  # [{"data"=>
+  #  [{"figi"=>"BBG000BLNNH6",
+  #    "name"=>"INTL BUSINESS MACHINES CORP",
+  #    "ticker"=>"IBM",
+  #    "exchCode"=>"US",
+  #    "compositeFIGI"=>"BBG000BLNNH6",
+  #    "uniqueID"=>"EQ0010080100001000",
+  #    "securityType"=>"Common Stock",
+  #    "marketSector"=>"Equity",
+  #    "shareClassFIGI"=>"BBG001S5S399",
+  #    "uniqueIDFutOpt"=>nil,
+  #    "securityType2"=>"Common Stock",
+  #    "securityDescription"=>"IBM"},
+  #   {"figi"=>"BBG000BLNNV0",
+  #    "name"=>"INTL BUSINESS MACHINES CORP",
+  #    "ticker"=>"IBM",
+  #    "exchCode"=>"UA",
+  #    "compositeFIGI"=>"BBG000BLNNH6",
+  #    "uniqueID"=>"EQ0010080100001000",
+  #    "securityType"=>"Common Stock",
+  #    "marketSector"=>"Equity",
+  #    "shareClassFIGI"=>"BBG001S5S399",
+  #    "uniqueIDFutOpt"=>nil,
+  #    "securityType2"=>"Common Stock",
+  #    "securityDescription"=>"IBM"},
+  #   ...
+
+r = client.map(isin: 'US4592001014', exchCode: 'US')
+r = client.map(idType: 'ID_ISIN', idValue: 'US4592001014', exchCode: 'US')
+
+# one can query for multiple items
+r = client.map([
+  { isin: 'US4592001014' },
+  { idType: 'ID_WERTPAPIER', idValue: '851399', exchCode: 'US' } ])
+```
+
+Query for search ([/v2/search](https://www.openfigi.com/api#post-v2-search)):
+```ruby
+r = client.search('ibm')
+r = client.search(query: 'ibm')
+r = client.search('ibm', exchCode: 'US')
+r = client.search(query: 'ibm', exchCode: 'US')
+
+pp r
+  # ==>
+  # {"data"=>
+  #   [{"figi"=>"BBG00196W5Z9",
+  #     "name"=>"Ibm",
+  #     "ticker"=>"IBMD=4",
+  #     "exchCode"=>"OC",
+  #     "compositeFIGI"=>nil,
+  #     "uniqueID"=>"EF12901854300074186897",
+  #     "securityType"=>"DIVIDEND NEUTRAL STOCK FUTURE",
+  #     "marketSector"=>"Equity",
+  #     "shareClassFIGI"=>nil,
+  #     "uniqueIDFutOpt"=>"IBMD=4 OC Equity",
+  #     "securityType2"=>"Future",
+  #     "securityDescription"=>"IBMD=4"},
+  #    {"figi"=>"BBG00196W5Y0",
+  #     "name"=>"Ibm",
+  #     "ticker"=>"IBMD=3",
+  #     "exchCode"=>"OC",
+  #     "compositeFIGI"=>nil,
+  #     "uniqueID"=>"EF12901854290074186860",
+  #     "securityType"=>"DIVIDEND NEUTRAL STOCK FUTURE",
+  #     "marketSector"=>"Equity",
+  #     "shareClassFIGI"=>nil,
+  #     "uniqueIDFutOpt"=>"IBMD=3 OC Equity",
+  #     "securityType2"=>"Future",
+  #     "securityDescription"=>"IBMD=3"},
+  #    ...
+```
+
+Search and `#next`:
+```ruby
+r = client.search('ibm')
+  #
+  # grab the first "page" of results
+
+r = r.next
+  #
+  # grab the next page of results
+
+# ...
+```
+
 
 ## license
 

data/lib/figa.rb

@@ -5,7 +5,7 @@ require 'net/http'
 
 module Figa
 
-  VERSION = '0.0.1'
+  VERSION = '0.1.0'
 
   USER_AGENT = "Figa - https://github.com/jmettraux/figa - #{VERSION}"
   API_ROOT_URI = 'https://api.openfigi.com/v2'
@@ -18,28 +18,16 @@ module Figa
       @enum_values = {}
     end
 
-    def map(h)
+    def map(array_or_hash)
 
-      k0 = h.is_a?(Hash) ? h.keys.first.to_s : nil
+      a = to_mapping_parameter_array(array_or_hash)
 
-      if k0 && h.size == 1 && enum_values('idType').include?(k0)
-
-        h = { idType: h.keys.first, idValue: h.values.first }
-      end
-
-      validate(h)
-
-      fail ArgumentError.new("parameter 'idType' is missing"
-        ) unless h[:idType] || h['idType']
-      fail ArgumentError.new("parameter 'idValue' is missing"
-        ) unless h[:idValue] || h['idValue']
-
-      post('/mapping', h)
+      post('/mapping', a)
     end
 
-    def search(h)
+    def search(q, h={})
 
-      h = { query: h } unless h.is_a?(Hash)
+      h = q.is_a?(String) ? h.merge(query: q) : q
 
       validate(h)
 
@@ -51,35 +39,56 @@ module Figa
 
     protected
 
-    ENUM_KEYS = %w[
-      idType exchCode micCode currency marketSecDes securityType securityType2 ]
+    def to_mapping_parameter_array(aoh)
+
+      a = aoh.is_a?(Array) ? aoh : [ aoh ]
+
+      id_types = enum_values('idType')
 
-    def list_enum_values(key)
+      a.collect do |h|
 
-      #fail ArgumentError.new(
-      #  "key #{key.inspect} not included in #{KEYS.inspect}"
-      #) unless KEYS.include?(key)
+        oldk, itk =
+          h.keys.inject(nil) { |r, k|
+            next r if r
+            kk = k.upcase; next [ k, kk ] if id_types.include?(kk)
+            kk = "ID_#{kk}"; next [ k, kk ] if id_types.include?(kk)
+            nil }
+        if oldk
+          h[:idType] = itk
+          h[:idValue] = h.delete(oldk)
+        end
 
-      get('/mapping/values/' + key)
+        validate(h)
+
+        fail ArgumentError.new("parameter 'idType' is missing"
+          ) unless h[:idType] || h['idType']
+        fail ArgumentError.new("parameter 'idValue' is missing"
+          ) unless h[:idValue] || h['idValue']
+
+        h
+      end
     end
 
+    ENUM_KEYS = %w[
+      idType exchCode micCode currency marketSecDes securityType securityType2 ]
+
     def enum_values(key)
 
-      @enum_values[key] ||= list_enum_values(key)
+      @enum_values[key] ||= get('/mapping/values/' + key)['values']
     end
 
     def validate(h)
 
+      fail ArgumentError.new("#{h.inspect} is not a Hash") unless h.is_a?(Hash)
+
       h.each do |k, v|
 
         sk = k.to_s
         next unless ENUM_KEYS.include?(sk)
 
-        vs = (@enum_values[sk] ||= list_enum_values(key))
-
         fail ArgumentError.new(
           "value #{v.inspect} is not a valid value for key #{k.inspect}"
-        ) unless enum_values(keys).include?(v)
+        ) unless enum_values(sk).include?(v)
       end
     end
 
@@ -88,7 +97,7 @@ module Figa
 
     def request(method, uri, data=nil)
 
-      uri = API_ROOT_URI + uri
+      uri = API_ROOT_URI + uri unless uri.match(/\Ahttps:\/\//)
 
       req = (method == :post ? Net::HTTP::Post : Net::HTTP::Get).new(uri)
       req.instance_eval { @header.clear }
@@ -101,7 +110,7 @@ module Figa
 
       req.set_header('User-Agent', USER_AGENT)
       req.set_header('Accept', 'application/json')
-# TODO api key
+      req.set_header('X-OPENFIGI-APIKEY', @api_key) if @api_key
 
       u = URI(uri)
 
@@ -110,17 +119,27 @@ module Figa
       t = Net::HTTP.new(u.host, u.port)
       t.use_ssl = (u.scheme == 'https')
 #t.set_debug_output($stdout)
-#t.set_debug_output($stdout) if u.to_s.match(/search/)
+#t.set_debug_output($stdout) if uri.match(/search/)
 
       res = t.request(req)
 
-      #class << res; attr_accessor :_elapsed; end
-      #res._elapsed = monow - t0
-
       j = JSON.parse(res.body)
-      def j._response; res; end
-      j['_elapsed'] = monow - t0
-# TODO j['next']
+        #
+      class << j
+        attr_accessor :_response, :_client, :_elapsed, :_method, :_uri, :_form
+      end
+        #
+      j._response = res
+      j._client = self
+      j._elapsed = monow - t0
+      j._method = method
+      j._uri = uri
+      j._form = data
+        #
+      def j.next
+        n = self['next']; return nil unless n && n.is_a?(String)
+        _client.send(:request, _method, _uri, _form.merge(start: n))
+      end if j.is_a?(Hash)
 
       j
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: figa
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - John Mettraux
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-06-13 00:00:00.000000000 Z
+date: 2019-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec