tcg-player-sdk 0.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 444973875234b87717e9ece0dd3c0373d707d2a13bac732330f7ab8d6a740f72
+  data.tar.gz: cc526ef5f4bc6cadb4404096dfdf9b5a414b5a438d99c4ddf58171b2b6beb214
+SHA512:
+  metadata.gz: cdede9b22fe30a6f4106af572ca2f0523e6989ec426de0d307fdc37252cfee511ed6275bae255d954eb9cd386465042d650ac78a6096e522d2810cbe26d1d6bb
+  data.tar.gz: e4649464a2dd938a07b9ee991cd1b9635248d36685f4f301feb31a5dcded44c43446f32e6a5172cf688938d2e36725c4277b1ef2e2e4e716f0aef7d75445b91a

data/lib/tcg-player-sdk/bearer_token.rb

@@ -0,0 +1,20 @@
+class TCGPlayerSDK::BearerToken
+  attr_accessor :expires_in, :token, :expiration, :issued
+
+  def initialize(params = {})
+    self.expires_in = params['expires_in']
+    self.token = params['access_token']
+    self.issued = DateTime.parse(params['.issued'])
+    self.expiration = DateTime.parse(params['.expires'])
+  end
+
+  ##
+  # @return true if the bearer token is within five minutes of expiring
+  def expired?
+    return expiration.nil? || (DateTime.now >= expiration)
+  end
+
+  def to_s
+    ap self, indent: -2
+  end
+end

data/lib/tcg-player-sdk/pokemon.rb

@@ -0,0 +1,41 @@
+# Helpers for pokemon-centric tasks
+class TCGPlayerSDK::Pokemon
+  attr_accessor :tcg
+
+  def initialize(_tcg)
+    self.tcg = _tcg
+    @category = nil
+  end
+
+  def category
+    @category ||= tcg.categories(limit: 100).select{|c| c.name =~ /Pokemon/i}.first
+  end
+
+  def categoryId
+    category.categoryId
+  end
+
+  def manifest
+    @manifest ||= tcg.category_search_manifest(categoryId)
+  end
+
+  ##
+  # Returns the TCGPlaeryAPI filter corresponding to Sets
+  def sets
+    @set_filter ||= @manifest.results.first.filters.select{|f| f.name == 'SetName'}.first
+  end
+
+  ##
+  # Returns the TCGPlayerSDK filter item corresponding to the input set
+  #
+  #   pokemon.set('Base Set')
+  #   [
+  #       [0] TCGPlayerSDK::ResponseStruct {
+  #            :text => "Base Set",
+  #           :value => "Base Set"
+  #       }
+  #   ]
+  def set(set_name)
+    sets.items.select{|i| i.text == set_name}
+  end
+end

data/lib/tcg-player-sdk/product_price_list.rb

@@ -0,0 +1,84 @@
+class TCGPlayerSDK::ProductPriceList
+  attr_accessor :response
+
+  ##
+  # Group prices by product ID.  This will set
+  # prices to an empty hash if there was an error.  Check response.errors for details about any errors.
+  #
+  # @param _response[TCGPlayerSDK::ResponseStruct] the result of calling TCGPlayerAPI#product_pricing
+  def initialize(_response)
+    @response = _response
+
+    if(response.success && response.results)
+      @prices = response.results.map{|r| TCGPlayerSDK::ProductPrice.new(r)}.group_by{|r| r.productId}
+    else
+      @prices = {}
+    end
+  end
+
+  ##
+  # Returns a hash with productIds as keys, and a list of prices with subtypes as values:
+  #   {
+  #     85736 => [
+  #         {
+  #                  "productId" => 85737,
+  #                   "lowPrice" => 4.99,
+  #                   "midPrice" => 5.63,
+  #                  "highPrice" => 7.73,
+  #                "marketPrice" => 10.35,
+  #             "directLowPrice" => nil,
+  #                "subTypeName" => "Reverse Holofoil"
+  #         },
+  #         {
+  #                  "productId" => 85737,
+  #                   "lowPrice" => nil,
+  #                   "midPrice" => nil,
+  #                  "highPrice" => nil,
+  #                "marketPrice" => nil,
+  #             "directLowPrice" => nil,
+  #                "subTypeName" => "Unlimited Holofoil"
+  #         },
+  #     ]
+  #   }
+  #
+  # @return [Hash<Integer, Array<TCGPlayerSDK::ProductPrice>>]
+  def prices
+    @prices
+  end
+
+  ##
+  # Weed out any ProductPrice objects that have no valid prices.
+  #
+  # @return [Hash<Integer, Array<TCGPlayerSDK::ProductPrice>>]
+  def valid_prices
+    valid_prices = {}
+    @prices.each do |id, prl|
+      valid_prices[id] ||= []
+      valid_prices[id] = prl.select{|pr| pr.has_valid_prices?}
+    end
+
+    return valid_prices
+  end
+end
+
+# A wrapper around the ResponseStruct for an individual product subtype's price.
+#         {
+#                  "productId" => 85737,
+#                   "lowPrice" => nil,
+#                   "midPrice" => nil,
+#                  "highPrice" => nil,
+#                "marketPrice" => nil,
+#             "directLowPrice" => nil,
+#                "subTypeName" => "Unlimited Holofoil"
+#         },
+class TCGPlayerSDK::ProductPrice < TCGPlayerSDK::ResponseStruct
+  def initialize(hash = nil)
+    super
+  end
+
+  ##
+  # @return [Boolean] Returns false if there are no non-nil prices
+  def has_valid_prices?
+    return !(lowPrice.nil? && midPrice.nil? && highPrice.nil? && directLowPrice.nil? && marketPrice.nil?)
+  end
+end

data/lib/tcg-player-sdk/response_struct.rb

@@ -0,0 +1,113 @@
+class TCGPlayerSDK::ResponseStruct < OpenStruct
+  include Enumerable
+
+  ##
+  # Attempt to execute a given block of code.  Return the result on success,
+  # or the *default* on failure.
+  #
+  #   try(nil) {self.results.first.name}
+  def try(default, &blk)
+    begin
+      return self.instance_eval(&blk)
+    rescue
+      return default
+    end
+  end
+
+  ##
+  # Iterates over `self.results` and attempts to fetch any missing results.
+  # For example, if you get a response that has "totalItems" equal to a number that is larger
+  # than the size of "results", then this function easily lets you iterate over every item,
+  # and will automatically fetch any items not included in "results."
+  #
+  # Since this class includes Enumberable, any Enumerable methods are also available.
+  #
+  # Example:
+  #   2.7.2 :057 > cl = tcg.categories
+  #    D, [2022-01-25T22:20:34.597036 #67042] DEBUG -- : Query: https://api.tcgplayer.com/catalog/categories params:
+  #    D, [2022-01-25T22:20:34.597129 #67042] DEBUG -- : {}
+  #    TCGPlayerSDK::ResponseStruct {
+  #        :totalItems => 67,
+  #        :results => [...]
+  #
+  #    2.7.2 :072 > cl.results.size
+  #    10
+  #
+  #    2.7.2 :073 > allcl = cl.map{|result| result.name}
+  #    D, [2022-01-25T22:29:11.506994 #67042] DEBUG -- : Query: https://api.tcgplayer.com/catalog/categories params:
+  #    D, [2022-01-25T22:29:11.507161 #67042] DEBUG -- : {
+  #       :offset => 10,
+  #       :limit => 100
+  #     }
+  #     [
+  #     [ 0] "Alternate Souls",
+  #     [ 1] "Architect TCG",
+  #     [ 2] "Argent Saga TCG",
+  #     [ 3] "Axis & Allies",
+  #     ...
+  #     [64] "WoW",
+  #     [65] "YuGiOh",
+  #     [66] "Zombie World Order TCG"
+  #     ]
+  def each(&block)
+    if(!self.totalItems.nil? && !self.results.nil? && !self.tcg_object.nil?)
+      max_items = self.totalItems
+
+      # Defaults
+      offset = self.results.size
+      limit = defined?(self.base_query.params.limit) ? self.base_query.params.limit : 100
+      offset += defined?(self.base_query.params.offset) ? self.base_query.params.offset : 0
+
+      self.results.each(&block)
+      while(offset < max_items && !self.results.empty?)
+        # Fetch more results
+        fetch_params = self.base_query.params.dup.to_h
+        fetch_params[:offset] = offset
+        fetch_params[:limit] = limit
+        more_results = self.tcg_object.query(self.base_query.url, fetch_params)
+
+        # iterate
+        more_results.results.each(&block)
+        offset += more_results.results.size
+      end
+    else
+      # Throw an exception?
+    end
+  end
+
+  # Create ResponseStructs out of any nested hashes or arrays of hashes
+  def method_missing(mid, *args)
+    # Avoid assignments
+    if(mid.to_s =~ /=/)
+      return super
+    else
+      # Get original value
+      value = super
+
+      # Turn it into a ResponseStruct
+      new_val = (value.is_a?(Array) && value.first.is_a?(Hash)) ?
+                  value.map{|v| TCGPlayerSDK::ResponseStruct.new(v)} :
+                  ((value.is_a?(Hash)) ? TCGPlayerSDK::ResponseStruct.new(value) : value)
+
+      # Save it back as a ResponseStruct
+      send("#{mid.to_s}=", new_val)
+      return new_val
+    end
+  end
+
+  def respond_to_missing?(mid, include_private = nil)
+    super
+  end
+
+  def to_s
+    ap self, indent: -2
+  end
+
+  def to_h(*args)
+    self.marshal_dump
+  end
+
+  def keys
+    return self.to_h.keys
+  end
+end

data/lib/tcg-player-sdk/tcg_player_sdk.rb

@@ -0,0 +1,142 @@
+##
+# Wrap up request handling and common functions for TCGPlayer price API
+class TCGPlayerSDK
+  attr_accessor :bearer_token, :user_agent, :logger, :noretry, :public_key, :private_key
+
+  API_VERSION = '1.39'
+  BASE_URL = 'https://api.tcgplayer.com'
+  TOKEN_URL = "#{BASE_URL}/token"
+  CATALOG_URL = "#{BASE_URL}/catalog"
+  CATEGORIES_URL = "#{CATALOG_URL}/categories"
+  PRICING_URL = "#{BASE_URL}/pricing"
+
+  ##
+  # @param params[Hash]
+  #   - user_agent: An identifying user agent string to be passed along with each request
+  #   - bearer_token: Optionally pass in a previously authenticated bearer token
+  #   - noretry: Set this to true to disable retrying queries when the bearer token is invalid
+  #   - logger: Optionally pass a custom logging object
+  #   - debug: Set output verbosity to DEBUG.  Default verbosity is WARN
+  def initialize(params = {})
+    self.user_agent = params[:user_agent] || 'Unknown'
+    self.bearer_token = params[:bearer_token]
+    self.noretry = params[:noretry]
+
+    self.public_key = params[:public_key]
+    self.private_key = params[:private_key]
+
+    # Setup logging
+    self.logger = params[:logger] || Logger.new(STDOUT)
+    if(params[:debug])
+      self.logger.level = Logger::DEBUG
+    else
+      self.logger.level = Logger::WARN
+    end
+  end
+
+  # Get a new bearer token.  Specify your app's public and private key as parameters
+  # or via Environment variables (or via .env) TCG_PLAYER_API_PUBLIC_KEY and TCG_PLAYER_API_PRIVATE_KEY
+  #
+  # @param params[Hash]
+  #   - public_key: your TCP Player API pubic key
+  #   - private_key: your TCP Player API pubic key
+  #
+  # @return [TCGPlayerSDK::BearerToken]
+  def authorize(params = {})
+    pub_key = params[:public_key] || public_key || ENV['TCG_PLAYER_API_PUBLIC_KEY']
+    pri_key = params[:private_key] || private_key || ENV['TCG_PLAYER_API_PRIVATE_KEY']
+
+    #"grant_type=client_credentials&client_id=PUBLIC_KEY&client_secret=PRIVATE_KEY"
+    query_params = {grant_type: 'client_credentials', client_id: pub_key, client_secret: pri_key}
+    response = HTTP.post(TOKEN_URL, form: query_params)
+    resp_hash = response.parse
+    logger.info resp_hash
+
+    self.bearer_token = BearerToken.new resp_hash
+  end
+
+  ##
+  # Perform a query on the TCGPlayer API
+  #
+  # @param url The API endpoint url, without arguments
+  # @param _params[Hash]
+  #   - post: When true, use a post request instead of a get request
+  #   - noretry: Override any other retry settings and skip retry if true
+  #   - *: Additional entries in _params hash are passed through to API as arguments
+  #
+  # @return [TCGPlayerSDK::ResponseStruct]
+  def query(url, _params = {})
+    params = _params.dup
+    post = params.delete :post
+    method = post ? 'post' : 'get'
+    pkey = post ? :json : :params
+    skip_retry = params.delete(:noretry) || noretry
+
+    logger.debug "Query: #{url} params: "
+    logger.ap params
+
+    # Check for expiration of bearer token
+    response = HTTP.auth("bearer #{bearer_token ? bearer_token.token : 'none'}").headers('User-Agent' => user_agent).send(method, url, pkey => params)
+    ret = ResponseStruct.new response.parse.merge({base_query: {url: url, params: _params}, http_response: response, tcg_object: self})
+
+    # Detect an invalid bearer token and attempt to retry
+    if(!skip_retry && ret.errors && ret.errors.size > 0 && ret.errors.reduce(false){|sum, err| sum = (sum || (err =~ /bearer token/))})
+      # Reauthorize and try again
+      authorize
+      ret = query(url, _params.merge({noretry: true}))
+    end
+
+    return ret
+  end
+
+  ##
+  # Endpoint https://docs.tcgplayer.com/reference/catalog_getcategories-1
+  #
+  # @param params[Hash]
+  #   - limit: max to return (default 10)
+  #   - offset: number of categories to skip (for paging)
+  #   - sort_order: property to sort by (defaults to name)
+  #   - sort_desc: descending sort order
+  #
+  # @return [TCGPlayerSDK::ResponseStruct]
+  def categories(params = {})
+    query(CATEGORIES_URL, params)
+  end
+
+  ##
+  # https://docs.tcgplayer.com/reference/catalog_getcategory-1
+  #
+  # @return [TCGPlayerSDK::ResponseStruct]
+  def category_details(ids)
+    query("#{CATEGORIES_URL}/#{ids.join(',')}")
+  end
+
+  # https://docs.tcgplayer.com/reference/catalog_getcategorysearchmanifest
+  #
+  # @return [TCGPlayerSDK::ResponseStruct]
+  def category_search_manifest(id)
+    query("#{CATEGORIES_URL}/#{id}/search/manifest")
+  end
+
+  # https://docs.tcgplayer.com/reference/catalog_searchcategory
+  #
+  # @return [TCGPlayerSDK::ResponseStruct]
+  def category_search_products(id, params = {})
+    search_params = {post: true}.merge(params)
+    query("#{CATEGORIES_URL}/#{id}/search", search_params)
+  end
+
+  #def product_details(pids, params = {})
+  #  query("#{CATEGORIES_URL}/#{id}/search", search_params)
+  #end
+
+  ##
+  # Accessor to https://docs.tcgplayer.com/reference/pricing_getproductprices-1
+  #
+  # @param ids An array of product IDs to query
+  # @return [TCGPlayerSDK::ProductPriceList]
+  def product_pricing(_ids)
+    ids = _ids.is_a?(Array) ? _ids.join(',') : _ids
+    TCGPlayerSDK::ProductPriceList.new(query("#{PRICING_URL}/product/#{ids}"))
+  end
+end

data/lib/tcg-player-sdk.rb

@@ -0,0 +1,11 @@
+require 'http'
+require 'logger'
+require 'amazing_print'
+require 'dotenv/load'
+
+require 'tcg-player-sdk/tcg_player_sdk'
+require 'tcg-player-sdk/bearer_token'
+require 'tcg-player-sdk/response_struct'
+require 'tcg-player-sdk/product_price_list'
+require 'tcg-player-sdk/pokemon'
+

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: tcg-player-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.3
+platform: ruby
+authors:
+- Carl Svensson
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-02-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.0.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.0.4
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.7.6
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.7.6
+- !ruby/object:Gem::Dependency
+  name: amazing_print
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.0
+description: The tcg-player-sdk gem is a convenient wrapper to the TCGPlayer JSON
+  API.  Easily query the entire API, with helpers and accessors for common queries.  This
+  gem also provides helpers for Pokemon-specific queries.  A work in progress.
+email: csvenss2@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/tcg-player-sdk.rb
+- lib/tcg-player-sdk/bearer_token.rb
+- lib/tcg-player-sdk/pokemon.rb
+- lib/tcg-player-sdk/product_price_list.rb
+- lib/tcg-player-sdk/response_struct.rb
+- lib/tcg-player-sdk/tcg_player_sdk.rb
+homepage: https://cecomp64.github.io/tcg-player-sdk/
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key:
+specification_version: 4
+summary: A Ruby interface to the TCGPlayer.com API for trading card prices.
+test_files: []