openfigi_ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bb96df5aae03995901f25a8e042064c881d7d43bd2763d2164feca902588c797
+  data.tar.gz: b7d083008c394a57fd000480eabdf52348c7f207c1a17a7db9435112402a8aea
+SHA512:
+  metadata.gz: a027a62e72d4f2c7e18f2da594fe15576f9fcc49d5ec1d443ccdaec26457fdd4924e548dade296e2ba701ce1d585ab98e733567436a3403a82d0549c9abeaae5
+  data.tar.gz: 0b147217f140a7bd5d810e148f474c4fa0c51bcd5841924234b331f19778179079f478aae1d1d28d9dfcb24f00f09487e0c40395e07ca4333c440e1754c3e624

data/.yardopts

@@ -0,0 +1,6 @@
+--no-private
+--markup markdown
+--output-dir doc/
+lib/**/*.rb
+-
+README.md

data/CLAUDE.md

@@ -0,0 +1,76 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+bin/setup          # Install dependencies
+bin/console        # Open IRB session with the gem loaded (for manual testing)
+bundle exec rake   # Run default rake tasks
+gem build          # Build the .gem file
+```
+
+No test framework is configured. If tests are added, update this file with the test command.
+
+## Architecture
+
+A Ruby gem wrapping the [OpenFIGI V3 API](https://www.openfigi.com/api) — a financial data service for mapping identifiers (ISIN, CUSIP, ticker, etc.) to FIGIs (Financial Instrument Global Identifiers). V3 only; V2 is sunsetting.
+
+**Base URL:** `https://api.openfigi.com/v3`
+**Auth:** optional `X-OPENFIGI-APIKEY` header
+**Rate limits:** 25 req/min (unauthenticated) · 25 req/6s (authenticated) for mapping; lower limits for search/filter
+
+### Module layout
+
+```
+lib/openfigi_ruby.rb              # Entry point: requires all sub-files, exposes .configure
+lib/openfigi_ruby/
+  version.rb                      # VERSION constant
+  configuration.rb                # Configuration (api_key, open_timeout, read_timeout)
+  error.rb                        # Error hierarchy (see below)
+  client.rb                       # HTTP client — all API methods live here
+  figi_result.rb                  # FigiResult Struct (one matched instrument)
+  mapping_result.rb               # MappingResult Struct (data array or warning)
+  search_result.rb                # SearchResult and FilterResult Structs
+```
+
+### Client API
+
+```ruby
+OpenfigiRuby.configure { |c| c.api_key = ENV["OPENFIGI_API_KEY"] }
+client = OpenfigiRuby::Client.new   # uses global config; accepts api_key: override
+
+client.mapping([{ id_type: "ID_ISIN", id_value: "US4592001014" }])
+  # => [MappingResult(data: [FigiResult(...)], warning: nil)]
+
+client.mapping_values(:id_type)
+  # => ["ID_ISIN", "ID_CUSIP", ...]
+
+client.search(query: "Apple", exch_code: "US")
+  # => SearchResult(data: [...], next_page: "...", error: nil)
+
+client.filter(query: "Apple", currency: "USD")
+  # => FilterResult(data: [...], next_page: "...", total: 42, error: nil)
+```
+
+All input hashes use **snake_case** symbol keys; the client converts to camelCase for the API. Response structs use snake_case accessors. `next_page` holds the pagination token (the API field is `next`).
+
+### Error hierarchy
+
+```
+OpenfigiRuby::Error
+  └─ ApiError          (status_code:, body: attributes)
+       ├─ AuthenticationError   # HTTP 401
+       ├─ RateLimitError        # HTTP 429
+       ├─ InvalidRequestError   # HTTP 400
+       └─ ServerError           # HTTP 500/503
+```
+
+### Conventions
+
+- All files use `# frozen_string_literal: true`
+- Ruby >= 3.1.0 required
+- No runtime dependencies — uses only `net/http`, `json`, `uri` from stdlib
+- Runtime dependencies go in `openfigi_ruby.gemspec`; dev-only in `Gemfile`
+- Version is the single source of truth in `lib/openfigi_ruby/version.rb`

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phong Si
+
+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,174 @@
+# OpenfigiRuby
+
+Ruby client for the [OpenFIGI V3 API](https://www.openfigi.com/api). Maps financial identifiers (ISIN, CUSIP, ticker, etc.) to FIGIs (Financial Instrument Global Identifiers), with support for keyword search and filtering.
+
+## Installation
+
+```bash
+bundle add openfigi_ruby
+```
+
+Or add to your Gemfile manually:
+
+```ruby
+gem "openfigi_ruby"
+```
+
+## Usage
+
+### Configuration
+
+```ruby
+OpenfigiRuby.configure do |config|
+  config.api_key = ENV["OPENFIGI_API_KEY"]  # optional but recommended for higher rate limits
+  config.open_timeout = 10                  # seconds (default: 10)
+  config.read_timeout = 30                  # seconds (default: 30)
+end
+
+client = OpenfigiRuby::Client.new
+```
+
+You can also pass an API key per-client without touching global config:
+
+```ruby
+client = OpenfigiRuby::Client.new(api_key: "your_key")
+```
+
+---
+
+### Mapping identifiers to FIGIs
+
+`mapping` accepts up to 10 jobs per request (100 with an API key) and returns one result per job.
+
+```ruby
+results = client.mapping([
+  { id_type: "ID_ISIN",  id_value: "US0378331005" },
+  { id_type: "ID_CUSIP", id_value: "037833100" },
+  { id_type: "TICKER",   id_value: "AAPL", exch_code: "US" },
+])
+
+results.each do |result|
+  if result.found?
+    result.data.each do |figi|
+      puts "#{figi.name} — #{figi.figi} (#{figi.exch_code})"
+    end
+  else
+    puts "No match: #{result.warning}"
+  end
+end
+```
+
+**Optional filters per job:**
+
+| Key | Description |
+|---|---|
+| `:exch_code` | Exchange code (e.g. `"US"`, `"LN"`) |
+| `:mic_code` | Market Identifier Code |
+| `:currency` | Currency code (e.g. `"USD"`) |
+| `:market_sec_des` | Market sector description |
+| `:security_type` | Primary security type |
+| `:security_type2` | Secondary security type (required for `BASE_TICKER`/`ID_EXCH_SYMBOL`) |
+| `:include_unlisted_equities` | Boolean |
+| `:option_type` | `"Put"` or `"Call"` |
+| `:strike` | Two-element numeric range, e.g. `[100, 150]` |
+| `:expiration` | Two-element date range, e.g. `["2024-01-01", "2024-12-31"]` |
+| `:maturity` | Two-element date range (required for Pool) |
+| `:state_code` | US state code |
+
+---
+
+### Fetching valid enum values
+
+Look up the accepted values for any filterable field:
+
+```ruby
+client.mapping_values(:id_type)
+# => ["ID_ISIN", "ID_CUSIP", "TICKER", "ID_BB_GLOBAL", ...]
+
+client.mapping_values(:exch_code)
+# => ["US", "LN", "UN", ...]
+```
+
+Valid keys: `:id_type`, `:exch_code`, `:mic_code`, `:currency`, `:market_sec_des`, `:security_type`, `:security_type2`
+
+---
+
+### Keyword search
+
+Search for FIGIs by name or ticker. Results are paginated.
+
+```ruby
+result = client.search(query: "Apple", exch_code: "US", security_type: "Common Stock")
+
+result.data.each { |figi| puts "#{figi.ticker} — #{figi.figi}" }
+
+# Fetch the next page
+if result.next_page
+  result = client.search(query: "Apple", exch_code: "US", start: result.next_page)
+end
+```
+
+---
+
+### Filter
+
+Like search, but results are sorted alphabetically by FIGI and include a total count. Query is optional.
+
+```ruby
+result = client.filter(currency: "USD", security_type: "Common Stock")
+
+puts "#{result.total} total matches"
+result.data.each { |figi| puts figi.figi }
+
+# Paginate
+while result.next_page
+  result = client.filter(currency: "USD", security_type: "Common Stock", start: result.next_page)
+  result.data.each { |figi| puts figi.figi }
+end
+```
+
+---
+
+### Error handling
+
+```ruby
+begin
+  results = client.mapping([{ id_type: "TICKER", id_value: "AAPL" }])
+rescue OpenfigiRuby::AuthenticationError
+  # HTTP 401 — check your API key
+rescue OpenfigiRuby::RateLimitError
+  # HTTP 429 — back off and retry
+rescue OpenfigiRuby::InvalidRequestError => e
+  # HTTP 400 — malformed request
+  puts e.body
+rescue OpenfigiRuby::ServerError
+  # HTTP 500/503 — retry with exponential backoff
+rescue OpenfigiRuby::ApiError => e
+  # catch-all for any other non-200 response
+  puts "#{e.status_code}: #{e.message}"
+end
+```
+
+---
+
+### Rate limits
+
+| | Without API key | With API key |
+|---|---|---|
+| **Mapping** | 25 req/min, 10 jobs/req | 25 req/6s, 100 jobs/req |
+| **Search/Filter** | 5 req/min | 20 req/min |
+
+Get a free API key at [openfigi.com](https://www.openfigi.com/api#get-started).
+
+## Development
+
+```bash
+bin/setup          # install dependencies
+bin/console        # interactive prompt with the gem loaded
+bundle exec rake   # run tests
+bundle exec yard server  # browse docs at http://localhost:8808
+```
+
+## License
+
+[MIT](LICENSE.txt)

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "yard"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+YARD::Rake::YardocTask.new(:doc)
+
+task default: :test

data/lib/openfigi_ruby/client.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module OpenfigiRuby
+  # HTTP client for the OpenFIGI V3 API.
+  #
+  # Instantiate with an optional API key override, or configure globally via
+  # {OpenfigiRuby.configure} and call +Client.new+ with no arguments.
+  class Client
+    # Valid field names accepted by {#mapping_values}.
+    # @api private
+    MAPPING_VALUE_KEYS = %w[idType exchCode micCode currency marketSecDes securityType securityType2].freeze
+
+    # @param api_key [String, nil] overrides the globally configured key
+    # @param open_timeout [Integer] seconds before the connection times out
+    # @param read_timeout [Integer] seconds before the read times out
+    def initialize(
+      api_key: OpenfigiRuby.configuration.api_key,
+      open_timeout: OpenfigiRuby.configuration.open_timeout,
+      read_timeout: OpenfigiRuby.configuration.read_timeout
+    )
+      @api_key = api_key
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    # Maps third-party identifiers to FIGIs (POST /v3/mapping).
+    #
+    # @param jobs [Array<Hash>] each hash must include +:id_type+ and +:id_value+.
+    #   Optional keys: +:exch_code+, +:mic_code+, +:currency+, +:market_sec_des+,
+    #   +:security_type+, +:security_type2+, +:include_unlisted_equities+,
+    #   +:option_type+, +:strike+, +:contract_size+, +:coupon+,
+    #   +:expiration+, +:maturity+, +:state_code+.
+    # @return [Array<MappingResult>] one result per input job
+    #
+    # @example
+    #   client.mapping([
+    #     { id_type: "ID_ISIN", id_value: "US4592001014" },
+    #     { id_type: "TICKER", id_value: "AAPL", exch_code: "US" }
+    #   ])
+    def mapping(jobs)
+      body = jobs.map { |job| serialize(job) }
+      response = post("/mapping", body)
+      response.map { |item| parse_mapping_result(item) }
+    end
+
+    # Returns the set of valid values for a filterable field (GET /v3/mapping/values/:key).
+    #
+    # @param key [String, Symbol] snake_case or camelCase field name.
+    #   Valid values: :id_type, :exch_code, :mic_code, :currency,
+    #   :market_sec_des, :security_type, :security_type2
+    # @return [Array<String>]
+    #
+    # @example
+    #   client.mapping_values(:id_type)
+    def mapping_values(key)
+      api_key = camelize(key.to_s)
+      response = get("/mapping/values/#{api_key}")
+      response["values"]
+    end
+
+    # Searches for FIGIs by keyword (POST /v3/search).
+    #
+    # @param query [String] search terms
+    # @param start [String, nil] pagination token from a previous {SearchResult#next_page}
+    # @param filters [Hash] optional snake_case filter keys (same as mapping job filters)
+    # @return [SearchResult]
+    #
+    # @example
+    #   result = client.search(query: "Apple", exch_code: "US")
+    #   result.data   #=> [#<struct OpenfigiRuby::FigiResult ...>, ...]
+    #   result.next_page  #=> "BBG..." or nil
+    def search(query:, start: nil, **filters)
+      body = { "query" => query }
+      body["start"] = start if start
+      body.merge!(serialize(filters))
+      response = post("/search", body)
+      parse_search_result(response)
+    end
+
+    # Filters FIGIs with alphabetical ordering and a total count (POST /v3/filter).
+    #
+    # @param query [String, nil] optional search terms
+    # @param start [String, nil] pagination token from a previous {FilterResult#next_page}
+    # @param filters [Hash] optional snake_case filter keys
+    # @return [FilterResult]
+    def filter(query: nil, start: nil, **filters)
+      body = {}
+      body["query"] = query if query
+      body["start"] = start if start
+      body.merge!(serialize(filters))
+      response = post("/filter", body)
+      parse_filter_result(response)
+    end
+
+    private
+
+    # OpenFIGI V3 API base URL.
+    # @api private
+    BASE_URL = "https://api.openfigi.com/v3"
+
+    def post(path, body)
+      uri = URI("#{BASE_URL}#{path}")
+      http = build_http(uri)
+      request = Net::HTTP::Post.new(uri)
+      apply_headers(request)
+      request.body = body.to_json
+      handle_response(http.request(request))
+    end
+
+    def get(path)
+      uri = URI("#{BASE_URL}#{path}")
+      http = build_http(uri)
+      request = Net::HTTP::Get.new(uri)
+      apply_headers(request)
+      handle_response(http.request(request))
+    end
+
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @open_timeout
+      http.read_timeout = @read_timeout
+      http
+    end
+
+    def apply_headers(request)
+      request["Content-Type"] = "application/json"
+      request["X-OPENFIGI-APIKEY"] = @api_key if @api_key
+    end
+
+    def handle_response(response)
+      body = response.body
+      code = response.code.to_i
+
+      case code
+      when 200
+        JSON.parse(body)
+      when 400
+        raise InvalidRequestError.new("Invalid request payload", status_code: code, body: body)
+      when 401
+        raise AuthenticationError.new("Invalid API key", status_code: code, body: body)
+      when 429
+        raise RateLimitError.new("Rate limit exceeded", status_code: code, body: body)
+      when 500, 503
+        raise ServerError.new("Server error (#{code})", status_code: code, body: body)
+      else
+        raise ApiError.new("Unexpected response (#{code})", status_code: code, body: body)
+      end
+    end
+
+    # Converts a hash with snake_case symbol keys to camelCase string keys,
+    # dropping any nil values.
+    def serialize(hash)
+      hash.each_with_object({}) do |(key, value), result|
+        next if value.nil?
+
+        result[camelize(key.to_s)] = value
+      end
+    end
+
+    # "id_type" => "idType", "security_type2" => "securityType2"
+    def camelize(snake_str)
+      parts = snake_str.split("_")
+      parts[0] + parts[1..].map(&:capitalize).join
+    end
+
+    def parse_mapping_result(item)
+      if item.key?("data")
+        MappingResult.new(data: item["data"].map { |r| build_figi_result(r) })
+      else
+        MappingResult.new(warning: item["warning"])
+      end
+    end
+
+    def parse_search_result(response)
+      SearchResult.new(
+        data: Array(response["data"]).map { |r| build_figi_result(r) },
+        next_page: response["next"],
+        error: response["error"]
+      )
+    end
+
+    def parse_filter_result(response)
+      FilterResult.new(
+        data: Array(response["data"]).map { |r| build_figi_result(r) },
+        next_page: response["next"],
+        total: response["total"],
+        error: response["error"]
+      )
+    end
+
+    def build_figi_result(hash)
+      FigiResult.new(
+        figi: hash["figi"],
+        security_type: hash["securityType"],
+        market_sector: hash["marketSector"],
+        ticker: hash["ticker"],
+        name: hash["name"],
+        exch_code: hash["exchCode"],
+        share_class_figi: hash["shareClassFIGI"],
+        composite_figi: hash["compositeFIGI"],
+        security_type2: hash["securityType2"],
+        security_description: hash["securityDescription"],
+        metadata: hash["metadata"]
+      )
+    end
+  end
+end

data/lib/openfigi_ruby/configuration.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module OpenfigiRuby
+  # Holds configuration for the gem. Set values via {OpenfigiRuby.configure}.
+  #
+  # @!attribute [rw] api_key
+  #   @return [String, nil] OpenFIGI API key. Without a key, stricter rate limits apply.
+  # @!attribute [rw] open_timeout
+  #   @return [Integer] seconds to wait when opening a connection (default: 10)
+  # @!attribute [rw] read_timeout
+  #   @return [Integer] seconds to wait for a response (default: 30)
+  class Configuration
+    # OpenFIGI V3 API base URL.
+    # @api private
+    BASE_URL = "https://api.openfigi.com/v3"
+
+    attr_accessor :api_key, :open_timeout, :read_timeout
+
+    def initialize
+      @api_key = nil
+      @open_timeout = 10
+      @read_timeout = 30
+    end
+  end
+end

data/lib/openfigi_ruby/error.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module OpenfigiRuby
+  # Base error class for all OpenfigiRuby errors.
+  class Error < StandardError; end
+
+  # Raised when the API returns a non-successful HTTP status.
+  #
+  # @!attribute [r] status_code
+  #   @return [Integer, nil] HTTP status code from the response
+  # @!attribute [r] body
+  #   @return [String, nil] raw response body
+  class ApiError < Error
+    attr_reader :status_code, :body
+
+    def initialize(message = nil, status_code: nil, body: nil)
+      super(message)
+      @status_code = status_code
+      @body = body
+    end
+  end
+
+  # Raised on HTTP 401 — invalid or missing API key.
+  class AuthenticationError < ApiError; end
+
+  # Raised on HTTP 429 — rate limit exceeded.
+  class RateLimitError < ApiError; end
+
+  # Raised on HTTP 400 — malformed request payload.
+  class InvalidRequestError < ApiError; end
+
+  # Raised on HTTP 500/503 — transient server errors (retry with backoff).
+  class ServerError < ApiError; end
+end

data/lib/openfigi_ruby/figi_result.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module OpenfigiRuby
+  # Represents a single financial instrument returned by the OpenFIGI API.
+  #
+  # @!attribute [r] figi
+  #   @return [String] the Financial Instrument Global Identifier (FIGI)
+  # @!attribute [r] security_type
+  #   @return [String, nil] primary security classification (e.g. "Common Stock", "ETP")
+  # @!attribute [r] market_sector
+  #   @return [String, nil] market sector (e.g. "Equity", "Corp", "Govt")
+  # @!attribute [r] ticker
+  #   @return [String, nil] exchange ticker symbol
+  # @!attribute [r] name
+  #   @return [String, nil] instrument name
+  # @!attribute [r] exch_code
+  #   @return [String, nil] exchange code (e.g. "US", "LN")
+  # @!attribute [r] share_class_figi
+  #   @return [String, nil] share class-level FIGI
+  # @!attribute [r] composite_figi
+  #   @return [String, nil] composite FIGI (aggregates listings across exchanges)
+  # @!attribute [r] security_type2
+  #   @return [String, nil] secondary security classification
+  # @!attribute [r] security_description
+  #   @return [String, nil] short description of the security
+  # @!attribute [r] metadata
+  #   @return [String, nil] optional metadata string returned by the API
+  FigiResult = Struct.new(
+    :figi,
+    :security_type,
+    :market_sector,
+    :ticker,
+    :name,
+    :exch_code,
+    :share_class_figi,
+    :composite_figi,
+    :security_type2,
+    :security_description,
+    :metadata,
+    keyword_init: true
+  )
+end

data/lib/openfigi_ruby/mapping_result.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module OpenfigiRuby
+  # Result for a single job in a bulk mapping request.
+  #
+  # On success, {data} is an array of {FigiResult} objects and {warning} is nil.
+  # When no match is found, {data} is nil and {warning} holds the API message.
+  #
+  # @!attribute [r] data
+  #   @return [Array<FigiResult>, nil] matched instruments, or nil when no match was found
+  # @!attribute [r] warning
+  #   @return [String, nil] API warning message when no identifier was found
+  MappingResult = Struct.new(:data, :warning, keyword_init: true) do
+    # Returns true if the job matched at least one instrument.
+    # @return [Boolean]
+    def found?
+      !data.nil? && !data.empty?
+    end
+  end
+end

data/lib/openfigi_ruby/search_result.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module OpenfigiRuby
+  # Result from POST /v3/search.
+  #
+  # @!attribute [r] data
+  #   @return [Array<FigiResult>] instruments matching the search query for this page
+  # @!attribute [r] next_page
+  #   @return [String, nil] opaque pagination token; pass as +start:+ to {Client#search} to fetch
+  #     the next page. nil when this is the last page.
+  # @!attribute [r] error
+  #   @return [String, nil] error message when the query itself is invalid
+  SearchResult = Struct.new(:data, :next_page, :error, keyword_init: true)
+
+  # Result from POST /v3/filter.
+  #
+  # Like {SearchResult} but results are sorted alphabetically by FIGI and a total count is included.
+  #
+  # @!attribute [r] data
+  #   @return [Array<FigiResult>] instruments matching the filter for this page
+  # @!attribute [r] next_page
+  #   @return [String, nil] opaque pagination token; pass as +start:+ to {Client#filter} to fetch
+  #     the next page. nil when this is the last page.
+  # @!attribute [r] total
+  #   @return [Integer] total number of matching instruments across all pages
+  # @!attribute [r] error
+  #   @return [String, nil] error message when the request is invalid
+  FilterResult = Struct.new(:data, :next_page, :total, :error, keyword_init: true)
+end

data/lib/openfigi_ruby/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module OpenfigiRuby
+  # Gem version string.
+  # @api private
+  VERSION = "0.1.0"
+end

data/lib/openfigi_ruby.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "openfigi_ruby/version"
+require_relative "openfigi_ruby/configuration"
+require_relative "openfigi_ruby/error"
+require_relative "openfigi_ruby/figi_result"
+require_relative "openfigi_ruby/mapping_result"
+require_relative "openfigi_ruby/search_result"
+require_relative "openfigi_ruby/client"
+
+# Ruby client for the OpenFIGI V3 API.
+#
+# Provides identifier mapping, keyword search, and filtering for Financial
+# Instrument Global Identifiers (FIGIs).
+#
+# @example Configure globally and create a client
+#   OpenfigiRuby.configure do |config|
+#     config.api_key = ENV["OPENFIGI_API_KEY"]
+#   end
+#
+#   client = OpenfigiRuby::Client.new
+#   results = client.mapping([{ id_type: "ID_ISIN", id_value: "US0378331005" }])
+module OpenfigiRuby
+  class << self
+    # Returns the global {Configuration} instance.
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configures the gem globally.
+    #
+    # @example
+    #   OpenfigiRuby.configure do |config|
+    #     config.api_key = ENV["OPENFIGI_API_KEY"]
+    #   end
+    # @yieldparam config [Configuration]
+    # @return [void]
+    def configure
+      yield configuration
+    end
+  end
+end

data/sig/openfigi_ruby.rbs

@@ -0,0 +1,4 @@
+module OpenfigiRuby
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: openfigi_ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Phong Si
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-05-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Maps financial identifiers (ISIN, CUSIP, ticker, etc.) to FIGIs via the
+  OpenFIGI V3 API. Supports bulk mapping, keyword search, and filtering.
+email: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/openfigi_ruby.rb
+- lib/openfigi_ruby/client.rb
+- lib/openfigi_ruby/configuration.rb
+- lib/openfigi_ruby/error.rb
+- lib/openfigi_ruby/figi_result.rb
+- lib/openfigi_ruby/mapping_result.rb
+- lib/openfigi_ruby/search_result.rb
+- lib/openfigi_ruby/version.rb
+- sig/openfigi_ruby.rbs
+homepage: https://github.com/phongsi/openfigi_ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/phongsi/openfigi_ruby
+  source_code_uri: https://github.com/phongsi/openfigi_ruby
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Ruby client for the OpenFIGI V3 API
+test_files: []