clash_of_clans_api 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a2b63aa46b4c6536b5c3c86729addc9e5dfa9c8071fdc890d24eed29d8768010
+  data.tar.gz: 4c2a7bf252282acd7f5254b22eab7fe5f273dd740c0179fb04926af0d8295fef
+SHA512:
+  metadata.gz: b9735602b7013aa396f555b1aca1d7dfc560cd6a46b27fd290275195f1a759c3789d116076ff10fe5ef5c8762371dfa2fdbebebc8f60930adf686c80b460aafe
+  data.tar.gz: ccdb84b96e9c4db19c6e1bb89cd142fdd200c22b953d3f4ed6e45051bc13b137d7e23d247487842dcc915fe7c97f07550813fcbb834657add06799e967a7563f

data/README.adoc

@@ -0,0 +1,67 @@
+== ClashOfClansApi
+
+`clash_of_clans_api` is a gem to communicate with the Clash of Clans API at https://developer.clashofclans.com/.
+It contains low-level methods to communicate with all existing API endpoints and aims to provide higher-level abstractions for them.
+
+=== Installation
+
+Add this line to your application’s Gemfile:
+
+[source,ruby]
+----
+gem 'clash_of_clans_api'
+----
+
+And then execute:
+
+....
+$ bundle install
+....
+
+Or install it yourself as:
+
+....
+$ gem install clash_of_clans_api
+....
+
+=== Usage
+
+==== API Communication
+
+To communicate with the Clash of Clans API, an API access token is required.
+Currently, the gem is not able to create tokens itself.
+
+The gem provides two classes for communication.
+`ClashOfClansApi::Api` is a low-level interface that implements methods for all API endpoints.
+If the request is successful, the API’s JSON response is parsed and returned, otherwise a `ClashOfClans::NoSucessError` is raised.
+`ClashOfClansApi::Client` is a higher-level interface that exposes its `ClashOfClansApi::Api` instance through `ClashOfClansApi::Client#api`.
+Both classes’ initializers take a single argument, the API token.
+
+The method names for the endpoints are the same in both classes.
+They are derived from the https://developer.clashofclans.com/#/documentation[API documentation] by the following steps.
+
+. Take the path name from the documentation (e.g. `/clans/{clanTag}/currentwar/leaguegroup`).
+. Replace slashes (`/`) with underscores (`\_`) and keep only inner ones (`clans_{clanTag}_currentwar_leaguegroup`).
+. In case of path arguments, singularize the path segment referenced by the argument (`clan_{clanTag}_currentwar_leaguegroup`).
+. Remove path argument segments (`clan_currentwar_leaguegroup`).
+
+Path arguments are converted to positional arguments in the order of definition in the original path name.
+Path arguments will automatically be URL-escaped.
+A URL query in the form of a `Hash` can be passed as the named parameter `query:`.
+
+==== Clan and player tags
+
+Tags in Clash of Clans are subject to format restrictions.
+Since those restrictions are well known, `ClashOfClansApi::Tags` provides class methods for checking the format (`.sanitizable?`) and sanitizing ill-formatted tags up to a certain degree (`.sanitize`).
+
+Even though the API seems to ignore some mistakes, e.g. using `O` (upper case letter o) instead of `0` (number zero), it also does not seem to correct them.
+If a player with tag `#PY0` existed, the API would return the same information for both `#PY0` and `#PYO`, except using the tag that was requested.
+This could lead to unforeseen errors like multiple database entries for the same player or clan.
+Therefore, those mistakes should be catched before sending a request.
+
+
+=== Development
+
+After checking out the repo, run `bin/setup` to install dependencies.
+Then, run `rake spec` to run the tests.
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/clash_of_clans_api/api.rb

@@ -0,0 +1,57 @@
+require_relative 'endpoint_methods'
+require_relative 'no_success_error'
+require_relative 'utils'
+
+module ClashOfClansApi
+	class Api
+		include EndpointMethods
+		
+		BASE_URI = URI('https://api.clashofclans.com/v1/')
+		
+		def base_uri
+			BASE_URI
+		end
+		
+		attr_reader :api_token
+		
+		def initialize(api_token)
+			@api_token = api_token
+		end
+		
+		def endpoint_headers
+			{
+				'Authorization' => "Bearer #{api_token}",
+			}
+		end
+		
+		define_endpoint :clan_currentwar_leaguegroup,     method: :get,  endpoint: proc { |clan_tag               | "clans/#{Utils.url_escape(clan_tag)}/currentwar/leaguegroup"                    }
+		define_endpoint :clanwarleagues_war,              method: :get,  endpoint: proc { | war_tag               | "clanwarleagues/wars/#{Utils.url_escape(war_tag)}"                              }
+		define_endpoint :clan_warlog,                     method: :get,  endpoint: proc { |clan_tag               | "clans/#{Utils.url_escape(clan_tag)}/warlog"                                    }
+		define_endpoint :clans,                           method: :get,  endpoint:                                     'clans'
+		define_endpoint :clan_currentwar,                 method: :get,  endpoint: proc { |clan_tag               | "clans/#{Utils.url_escape(clan_tag)}/currentwar"                                }
+		define_endpoint :clan,                            method: :get,  endpoint: proc { |clan_tag               | "clans/#{Utils.url_escape(clan_tag)}"                                           }
+		define_endpoint :clan_members,                    method: :get,  endpoint: proc { |clan_tag               | "clans/#{Utils.url_escape(clan_tag)}/members"                                   }
+		
+		define_endpoint :player,                          method: :get,  endpoint: proc { |player_tag             | "players/#{Utils.url_escape(player_tag)}"                                       }
+		define_endpoint :player_verifytoken,              method: :post, endpoint: proc { |player_tag             | "players/#{Utils.url_escape(player_tag)}/verifytoken"                           }, body: proc { |token:| %Q[{"token":"#{token.to_s}"}] }
+		
+		define_endpoint :leagues,                         method: :get,  endpoint:                                     'leagues'
+		define_endpoint :league_season,                   method: :get,  endpoint: proc { |   league_id, season_id|    "leagues/#{Utils.url_escape(   league_id)}/seasons/#{Utils.url_escape(season_id)}" }
+		define_endpoint :league,                          method: :get,  endpoint: proc { |   league_id           |    "leagues/#{Utils.url_escape(   league_id)}"                                  }
+		define_endpoint :league_seasons,                  method: :get,  endpoint: proc { |   league_id           |    "leagues/#{Utils.url_escape(   league_id)}/seasons"                          }
+		define_endpoint :warleague,                       method: :get,  endpoint: proc { |warleague_id           | "warleagues/#{Utils.url_escape(warleague_id)}"                                  }
+		define_endpoint :warleagues,                      method: :get,  endpoint:                                  'warleagues'
+		
+		define_endpoint :location_rankings_clans,         method: :get,  endpoint: proc { |location_id            | "locations/#{Utils.url_escape(location_id)}/rankings/clans"                     }
+		define_endpoint :location_rankings_players,       method: :get,  endpoint: proc { |location_id            | "locations/#{Utils.url_escape(location_id)}/rankings/players"                   }
+		define_endpoint :location_rankings_clansversus,   method: :get,  endpoint: proc { |location_id            | "locations/#{Utils.url_escape(location_id)}/rankings/clans-versus"              }
+		define_endpoint :location_rankings_playersversus, method: :get,  endpoint: proc { |location_id            | "locations/#{Utils.url_escape(location_id)}/rankings/players-versus"            }
+		define_endpoint :locations,                       method: :get,  endpoint:                                  'locations'
+		define_endpoint :location,                        method: :get,  endpoint: proc { |location_id            | "locations/#{Utils.url_escape(location_id)}"                                    }
+		
+		define_endpoint :goldpass_seasons_current,        method: :get,  endpoint:                                  'goldpass/seasons/current'
+		
+		define_endpoint :labels_players,                  method: :get,  endpoint:                                  'labels/players'
+		define_endpoint :labels_clans,                    method: :get,  endpoint:                                  'labels/clans'
+	end
+end

data/lib/clash_of_clans_api/client.rb

@@ -0,0 +1,46 @@
+require_relative 'api'
+require_relative 'models/league'
+
+module ClashOfClansApi
+	class Client
+		attr_reader :api
+		
+		def initialize(api_token)
+			@api = Api.new(api_token)
+		end
+		
+		def authorized?
+			api.perform_get('test').code == '404'
+		end
+		
+		def player_verifytoken(player_tag, token)
+			response = api.player_verifytoken(player_tag, token: token)
+			
+			raise "Sent player tag #{player_tag.inspect} but received #{response['tag'  ].inspect}." unless player_tag == response['tag'  ]
+			raise "Sent token #{     token     .inspect} but received #{response['token'].inspect}." unless token      == response['token']
+			
+			case response['status']
+			when 'ok'
+				true
+			when 'invalid'
+				false
+			else
+				raise "Unknown status #{response['status'].inspect}."
+			end
+		end
+		
+		def leagues
+			response = api.leagues
+			
+			raise NotImplementedError, "Found a paging cursor but handling it is not implemented yet." if response['paging']['cursors'].any?
+			
+			response['items'].map do |league|
+				Models::League.new(league)
+			end
+		end
+		
+		def league(id)
+			Models::League.new(api.league(id))
+		end
+	end
+end

data/lib/clash_of_clans_api/endpoint_methods.rb

@@ -0,0 +1,68 @@
+require 'cgi'
+require 'json'
+require 'net/https'
+
+module ClashOfClansApi
+	module EndpointMethods
+		def endpoint_headers
+			{}
+		end
+		
+		def perform_request(method, api_path, query: nil, body: nil, headers: nil)
+			uri = self.base_uri+api_path
+			uri.query = URI.encode_www_form(query) if query
+			
+			Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme=='https') do |http|
+				case method
+				when :get
+					Net::HTTP::Get
+				when :post
+					Net::HTTP::Post
+				else
+					raise ArgumentError, "Invalid method #{method.inspect}."
+				end.new(uri).tap do |request|
+					endpoint_headers.merge(headers || {}).each do |name, value|
+						request[name] = value
+					end
+					
+					if body
+						request['Content-Type'] = 'application/json'
+						request.body            = body
+					end
+				end.then do |request|
+					http.request(request)
+				end
+			end
+		end
+		
+		def transform_response(response)
+			if response.is_a?(Net::HTTPSuccess)
+				JSON.parse(response.body)
+			else
+				raise NoSuccessError.new(response)
+			end
+		end
+		
+		
+		def self.included(klass)
+			klass.extend(ClassMethods)
+		end
+		
+		module ClassMethods
+			def define_endpoint(name, method:, endpoint:, body: nil)
+				define_method(name) do |*args, **kwargs|
+					uri          = endpoint.respond_to?(:call) ? ClashOfClansApi::Utils.call_proc_without_unknown_keywords(endpoint, *args, **kwargs) : endpoint
+					request_body = body    .respond_to?(:call) ? ClashOfClansApi::Utils.call_proc_without_unknown_keywords(body,     *args, **kwargs) : body
+					
+					perform_request(method, uri, body: request_body, query: kwargs.dig(:query), headers: kwargs.dig(:headers)).then do |response|
+						if !kwargs.key?(:plain_response) || !kwargs.fetch(:plain_response)
+							transform_response(response)
+						else
+							response
+						end
+					end
+				end
+			end
+		end
+	end
+end

data/lib/clash_of_clans_api/models/base.rb

@@ -0,0 +1,71 @@
+require_relative 'invalid_data_error'
+
+module ClashOfClansApi
+	module Models
+		class Base
+			def initialize(hash)
+				@hash = hash
+				
+				validate!
+			end
+			
+			def to_h
+				@hash
+			end
+			
+			def [](key)
+				@hash[key]
+			end
+			
+			class << self
+				attr_reader :required_fields
+				
+				def property(name, key, type: nil, required: false)
+					define_method(name) do
+						if type.nil?
+							self[key]
+						else
+							if property_cached?(name)
+								property_from_cache(name)
+							else
+								cache_property(name, self[key].then do |prop|
+									prop.is_a?(Array) ? prop.map {|item| type.new(item) } : type.new(prop)
+								end)
+							end
+						end
+					end
+					
+					if required
+						@required_fields = (@required_fields || [])+[key]
+					end
+				end
+			end
+			
+			def property_cached?(name)
+				@property_cache && @property_cache.key?(name)
+			end
+			
+			def cache_property(name, obj)
+				@property_cache ||= {}
+				
+				@property_cache[name] = obj
+			end
+			
+			def property_from_cache(name)
+				@property_cache[name]
+			end
+			
+			def validate!
+				if self.class.required_fields
+					missing = self.class.required_fields.reject do |required_field|
+						@hash.key?(required_field)
+					end
+					
+					if missing.any?
+						raise InvalidDataError, "The following keys are required, but missing from the model data: #{missing.map(&:inspect).join(', ')}"
+					end
+				end
+			end
+		end
+	end
+end

data/lib/clash_of_clans_api/models/icon_set.rb

@@ -0,0 +1,12 @@
+require_relative 'base'
+
+module ClashOfClansApi
+	module Models
+		class IconSet < Base
+			property :tiny,   'tiny'
+			property :small,  'small'
+			property :medium, 'medium'
+			property :large,  'large'
+		end
+	end
+end

data/lib/clash_of_clans_api/models/invalid_data_error.rb

@@ -0,0 +1,13 @@
+module ClashOfClansApi
+	module Models
+		class InvalidDataError < StandardError
+			attr_reader :data_hash
+			
+			def initialize(message, data_hash=nil)
+				super(message)
+				
+				@data_hash = data_hash
+			end
+		end
+	end
+end

data/lib/clash_of_clans_api/models/league.rb

@@ -0,0 +1,12 @@
+require_relative 'base'
+require_relative 'icon_set'
+
+module ClashOfClansApi
+	module Models
+		class League < Base
+			property :id,        'id',       required: true
+			property :name,      'name',     required: true
+			property :icon_urls, 'iconUrls', type: IconSet
+		end
+	end
+end

data/lib/clash_of_clans_api/models/token.rb

@@ -0,0 +1,32 @@
+require_relative 'base'
+
+module ClashOfClansApi
+	module Models
+		class Token < Base
+			property :id,           'id',          required: true
+			property :developer_id, 'developerId'
+			property :tier,         'tier'
+			property :name,         'name',        required: true
+			property :description,  'description', required: true
+			property :origins,      'origins'
+			property :scopes,       'scopes'
+			property :cidr_ranges,  'cidrRanges',  required: true
+			property :valid_until,  'validUntil'
+			property :key,          'key',         required: true
+			
+			def initialize(hash, token_client:)
+				super(hash)
+				
+				@token_client = token_client
+			end
+			
+			def revoke
+				@token_client.revoke_api_key(self.id)
+			end
+			
+			def client_from_token
+				ClashOfClansApi::Client.new(self.key)
+			end
+		end
+	end
+end

data/lib/clash_of_clans_api/no_success_error.rb

@@ -0,0 +1,9 @@
+module ClashOfClansApi
+	class NoSuccessError < StandardError
+		attr_reader :response
+		
+		def initialize(response)
+			@response = response
+		end
+	end
+end

data/lib/clash_of_clans_api/tags.rb

@@ -0,0 +1,21 @@
+module ClashOfClansApi
+	module Tags
+		def self.tag_regex
+			/\A#[PYLQGRJCUV0289]+\z/
+		end
+		
+		def self.sanitizable_tag_regex
+			/\A\s*#?[PYLQGRJCUVO0289]+\s*\z/i
+		end
+		
+		def self.sanitizable?(tag)
+			sanitizable_tag_regex.match?(tag)
+		end
+		
+		def self.sanitize(tag)
+			tag.strip.upcase.gsub('O', '0').then do |t|
+				t.start_with?('#') ? t : "##{t}"
+			end
+		end
+	end
+end

data/lib/clash_of_clans_api/token_api.rb

@@ -0,0 +1,37 @@
+require_relative 'endpoint_methods'
+
+module ClashOfClansApi
+	module TokenApi
+		BASE_URI = URI('https://developer.clashofclans.com/api/')
+		
+		class << self
+			include EndpointMethods
+			
+			def base_uri
+				BASE_URI
+			end
+			
+			define_endpoint :login,         method: :post, endpoint: 'login',         body: proc { |email:, password:|
+				{
+					email:    email.to_s,
+					password: password.to_s,
+				}.to_json
+			}
+			define_endpoint :logout,        method: :post, endpoint: 'logout',        body: proc { '{}' }
+			define_endpoint :apikey_list,   method: :post, endpoint: 'apikey/list',   body: proc { '{}' }
+			define_endpoint :apikey_create, method: :post, endpoint: 'apikey/create', body: proc { |name:, description:, ip_addresses:|
+				{
+					name:        name,
+					description: description,
+					cidrRanges:  ip_addresses,
+					scopes:      [:clash],
+				}.to_json
+			}
+			define_endpoint :apikey_revoke, method: :post, endpoint: 'apikey/revoke', body: proc { |id:|
+				{
+					id: id,
+				}.to_json
+			}
+		end
+	end
+end

data/lib/clash_of_clans_api/token_client.rb

@@ -0,0 +1,61 @@
+require 'cgi'
+require_relative 'token_api'
+require_relative 'models/token'
+
+module ClashOfClansApi
+	class TokenClient
+		attr_reader :email
+		attr_reader :password
+		
+		def initialize(email, password)
+			@email    = email
+			@password = password
+		end
+		
+		def login!
+			TokenApi.login(email: email, password: password, plain_response: true).tap do |response|
+				if response.is_a?(Net::HTTPSuccess)
+					cookies = CGI::Cookie.parse(response['set-cookie'])
+					
+					@session_headers = {
+						'Cookie' => "session=#{cookies['session'][0]}",
+					}
+				else
+					raise NoSuccessError, response
+				end
+			end
+		end
+		
+		def logout
+			TokenApi.logout(headers: @session_headers)
+		ensure
+			@session_headers = nil
+		end
+		
+		def list_api_keys
+			response = TokenApi.apikey_list(headers: @session_headers)
+			
+			response['keys'].map do |key|
+				Models::Token.new(key, token_client: self)
+			end
+		end
+		
+		def create_api_key(name, description, ip_addresses)
+			response = TokenApi.apikey_create(name: name, description: description, ip_addresses: (ip_addresses.is_a?(Array) ? ip_addresses : [ip_addresses]), headers: @session_headers)
+			
+			Models::Token.new(response['key'], token_client: self)
+		end
+		
+		def revoke_api_key(id)
+			TokenApi.apikey_revoke(id: id, headers: @session_headers)
+			
+			true
+		end
+		
+		class << self
+			def create!(email, password)
+				new(email, password).login!
+			end
+		end
+	end
+end

data/lib/clash_of_clans_api/utils.rb

@@ -0,0 +1,34 @@
+require 'open-uri'
+
+module ClashOfClansApi
+	module Utils
+		def self.url_escape(string)
+			if !string.nil?
+				CGI.escape(string.to_s)
+			else
+				raise TypeError, 'cannot escape nil'
+			end
+		end
+		
+		def self.call_proc_without_unknown_keywords(proc, *args, **kwargs, &block)
+			params = proc.parameters.group_by(&:first).transform_values! do |m|
+				m.map do |s|
+					s[1]
+				end
+			end
+			
+			proc_keys =
+				if params.key?(:keyrest)
+					kwargs
+				else
+					kwargs.slice(*(params.values_at(:key, :keyreq).compact.flatten))
+				end
+			
+			proc.call(*args, **proc_keys, &block)
+		end
+		
+		def self.get_current_ipv4_address
+			IPAddr.new(URI('https://ipv4.icanhazip.com').open.read.strip).to_s
+		end
+	end
+end

data/lib/clash_of_clans_api/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ClashOfClansApi
+	VERSION = '0.1.1'
+end

data/lib/clash_of_clans_api.rb

@@ -0,0 +1,7 @@
+require_relative 'clash_of_clans_api/version'
+require_relative 'clash_of_clans_api/client'
+require_relative 'clash_of_clans_api/tags'
+require_relative 'clash_of_clans_api/token_client'
+
+module ClashOfClansApi
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: clash_of_clans_api
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- expeehaa
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-12-26 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- expeehaa@outlook.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.adoc
+- lib/clash_of_clans_api.rb
+- lib/clash_of_clans_api/api.rb
+- lib/clash_of_clans_api/client.rb
+- lib/clash_of_clans_api/endpoint_methods.rb
+- lib/clash_of_clans_api/models/base.rb
+- lib/clash_of_clans_api/models/icon_set.rb
+- lib/clash_of_clans_api/models/invalid_data_error.rb
+- lib/clash_of_clans_api/models/league.rb
+- lib/clash_of_clans_api/models/token.rb
+- lib/clash_of_clans_api/no_success_error.rb
+- lib/clash_of_clans_api/tags.rb
+- lib/clash_of_clans_api/token_api.rb
+- lib/clash_of_clans_api/token_client.rb
+- lib/clash_of_clans_api/utils.rb
+- lib/clash_of_clans_api/version.rb
+homepage: https://github.com/expeehaa/clash_of_clans_api
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.22
+signing_key:
+specification_version: 4
+summary: Client library for interacting with the ClashOfClans API.
+test_files: []