clash_of_clans_api 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2b63aa46b4c6536b5c3c86729addc9e5dfa9c8071fdc890d24eed29d8768010
-  data.tar.gz: 4c2a7bf252282acd7f5254b22eab7fe5f273dd740c0179fb04926af0d8295fef
+  metadata.gz: c028d861e525d6323453207f3f14885ed9df98346013bd5f586b34e79f95bd41
+  data.tar.gz: b39deae44556a97575faa02e5902a945bff658ad77367fb8f616045e2b705da7
 SHA512:
-  metadata.gz: b9735602b7013aa396f555b1aca1d7dfc560cd6a46b27fd290275195f1a759c3789d116076ff10fe5ef5c8762371dfa2fdbebebc8f60930adf686c80b460aafe
-  data.tar.gz: ccdb84b96e9c4db19c6e1bb89cd142fdd200c22b953d3f4ed6e45051bc13b137d7e23d247487842dcc915fe7c97f07550813fcbb834657add06799e967a7563f
+  metadata.gz: fffdf976c06723cc81d1134c58f832e24804729420d33fb3bc7645595ef6c0a54b45bcdfcbc68264ca6dfdaf58b525adde6cf7ac15802cdc30dae67e2ce08f16
+  data.tar.gz: 37644654dd7fdaa88b98d93648cd738a0aec546bf59be37e1443a69cd847b7219bf7426d56226aa1b43f19a59689f007b2be9bce3033ccee6b1d845851e0ea21

data/README.adoc

@@ -28,12 +28,12 @@ $ gem install clash_of_clans_api
 
 ==== 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.
+To communicate with the Clash of Clans API, an API key is required.
+If you like to use the library to create and manage API keys, see <<Token API>>.
 
 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.
+If the request is successful, the API’s JSON response is parsed and returned, otherwise an `ApiFrame::NoSuccessError` 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.
 
@@ -44,20 +44,52 @@ They are derived from the https://developer.clashofclans.com/#/documentation[API
 . 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`).
+. Remove any hyphens.
 
 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:`.
 
+==== Token API
+
+Creating, listing and deleting API keys (tokens) is supported in `ClashOfClansApi::TokenClient` using the email address and password from the Clash of Clans Developer website.
+
+[source,ruby]
+----
+token_client = ClashOfClansApi::TokenClient.new(email, password)
+token_client.login!
+
+# Return a list of the currently registered API keys.
+token_client.list_api_keys
+
+# Create a new API key for the IP address 127.0.0.1 and create a ClashOfClansApi::Client from it.
+token  = token_client.create_api_key('my_key_name', 'This is a description for my API key.', ['127.0.0.1'])
+client = token.client_from_token
+
+# Create or get an API key with the given name for the current IPv4 address.
+other_token = token_client.create_or_get_api_key_for_current_ipv4_address('test_key_name', overwrite: true)
+
+# Revoke the previously generated tokens.
+token_client.revoke_api_key(token.id)
+other_token.revoke
+
+# Logging out is not required, but possible.
+token_client.logout
+----
+
+This feature can be useful for applications whose host changes their IP address without human interaction as well as for large (federated) applications with too many requests for a single or a few manually created tokens.
+
+Similar to `ClashOfClansApi::Api` and `ClashOfClansApi::Client`, there is also a lower-level implementation of the token API in `ClashOfClansApi::TokenApi`.
+However, its usage is not recommended.
+
 ==== 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.
+Since the beginning of 2022, the API consistently corrects the letter `O` in requests to the number `0`, which was not the case before.
+Previously, this could lead to multiple database entries for the same player, which the `.sanitize` method could prevent.
+While this isn’t a problem anymore in this specific use case, it might come in handy for querying user input in ones own database.
 
 
 === Development

data/lib/clash_of_clans_api/api.rb

@@ -1,10 +1,10 @@
-require_relative 'endpoint_methods'
-require_relative 'no_success_error'
+require 'api_frame'
+
 require_relative 'utils'
 
 module ClashOfClansApi
 	class Api
-		include EndpointMethods
+		include ApiFrame::EndpointMethods
 		
 		BASE_URI = URI('https://api.clashofclans.com/v1/')
 		
@@ -18,40 +18,48 @@ module ClashOfClansApi
 			@api_token = api_token
 		end
 		
-		def endpoint_headers
+		def default_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'
+		define_endpoint :clan_currentwar_leaguegroup, method: :get, endpoint: proc { |clan_tag| "clans/#{ApiFrame::Utils.url_escape(clan_tag)}/currentwar/leaguegroup" }
+		define_endpoint :clanwarleagues_war,          method: :get, endpoint: proc { | war_tag| "clanwarleagues/wars/#{ApiFrame::Utils.url_escape(war_tag)}"           }
+		define_endpoint :clan_warlog,                 method: :get, endpoint: proc { |clan_tag| "clans/#{ApiFrame::Utils.url_escape(clan_tag)}/warlog"                 }
+		define_endpoint :clans,                       method: :get, endpoint:                   'clans'
+		define_endpoint :clan_currentwar,             method: :get, endpoint: proc { |clan_tag| "clans/#{ApiFrame::Utils.url_escape(clan_tag)}/currentwar"             }
+		define_endpoint :clan,                        method: :get, endpoint: proc { |clan_tag| "clans/#{ApiFrame::Utils.url_escape(clan_tag)}"                        }
+		define_endpoint :clan_members,                method: :get, endpoint: proc { |clan_tag| "clans/#{ApiFrame::Utils.url_escape(clan_tag)}/members"                }
+		define_endpoint :clan_capitalraidseasons,     method: :get, endpoint: proc { |clan_tag| "clans/#{ApiFrame::Utils.url_escape(clan_tag)}/capitalraidseasons"     }
+		
+		define_endpoint :player,             method: :get,  endpoint: proc { |player_tag| "players/#{ApiFrame::Utils.url_escape(player_tag)}"             }
+		define_endpoint :player_verifytoken, method: :post, endpoint: proc { |player_tag| "players/#{ApiFrame::Utils.url_escape(player_tag)}/verifytoken" }, body: proc { |token:| %Q({"token":"#{token}"}) }
+		
+		define_endpoint :capitalleagues,     method: :get, endpoint:                                               'capitalleagues'
+		define_endpoint :leagues,            method: :get, endpoint:                                                      'leagues'
+		define_endpoint :league_season,      method: :get, endpoint: proc { |           league_id, season_id |            "leagues/#{ApiFrame::Utils.url_escape(           league_id)}/seasons/#{ApiFrame::Utils.url_escape(season_id)}" }
+		define_endpoint :capitalleague,      method: :get, endpoint: proc { |    capitalleague_id            |     "capitalleagues/#{ApiFrame::Utils.url_escape(    capitalleague_id)}"                                                  }
+		define_endpoint :builderbaseleague,  method: :get, endpoint: proc { |builderbaseleague_id            | "builderbaseleagues/#{ApiFrame::Utils.url_escape(builderbaseleague_id)}"                                                  }
+		define_endpoint :builderbaseleagues, method: :get, endpoint:                                           'builderbaseleagues'
+		define_endpoint :league,             method: :get, endpoint: proc { |           league_id            |            "leagues/#{ApiFrame::Utils.url_escape(           league_id)}"                                                  }
+		define_endpoint :league_seasons,     method: :get, endpoint: proc { |           league_id            |            "leagues/#{ApiFrame::Utils.url_escape(           league_id)}/seasons"                                          }
+		define_endpoint :warleague,          method: :get, endpoint: proc { |        warleague_id            |         "warleagues/#{ApiFrame::Utils.url_escape(        warleague_id)}"                                                  }
+		define_endpoint :warleagues,         method: :get, endpoint:                                                   'warleagues'
+		
+		define_endpoint :location_rankings_clans,              method: :get, endpoint: proc { |location_id| "locations/#{ApiFrame::Utils.url_escape(location_id)}/rankings/clans"                }
+		define_endpoint :location_rankings_players,            method: :get, endpoint: proc { |location_id| "locations/#{ApiFrame::Utils.url_escape(location_id)}/rankings/players"              }
+		define_endpoint :location_rankings_clansversus,        method: :get, endpoint: proc { |location_id| "locations/#{ApiFrame::Utils.url_escape(location_id)}/rankings/clans-versus"         }
+		define_endpoint :location_rankings_playersbuilderbase, method: :get, endpoint: proc { |location_id| "locations/#{ApiFrame::Utils.url_escape(location_id)}/rankings/players-builder-base" }
+		define_endpoint :location_rankings_clansbuilderbase,   method: :get, endpoint: proc { |location_id| "locations/#{ApiFrame::Utils.url_escape(location_id)}/rankings/clans-builder-base"   }
+		define_endpoint :location_rankings_playersversus,      method: :get, endpoint: proc { |location_id| "locations/#{ApiFrame::Utils.url_escape(location_id)}/rankings/players-versus"       }
+		define_endpoint :locations,                            method: :get, endpoint:                      'locations'
+		define_endpoint :location_rankings_capitals,           method: :get, endpoint: proc { |location_id| "locations/#{ApiFrame::Utils.url_escape(location_id)}/rankings/capitals"             }
+		define_endpoint :location,                             method: :get, endpoint: proc { |location_id| "locations/#{ApiFrame::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

@@ -1,5 +1,9 @@
 require_relative 'api'
+require_relative 'models/paginated_response'
+require_relative 'models/clan'
+require_relative 'models/player'
 require_relative 'models/league'
+require_relative 'models/war'
 
 module ClashOfClansApi
 	class Client
@@ -10,7 +14,27 @@ module ClashOfClansApi
 		end
 		
 		def authorized?
-			api.perform_get('test').code == '404'
+			api.perform_request(:get, 'test').code == '404'
+		end
+		
+		def clan_currentwar(clan_tag)
+			Models::War.new(api.clan_currentwar(clan_tag), self)
+		end
+		
+		def clan_warlog(clan_tag)
+			Models::PaginatedResponse.new(Models::War, api.clan_warlog(clan_tag), self)
+		end
+		
+		def clan(tag)
+			Models::Clan.new(api.clan(tag), self)
+		end
+		
+		def clan_members(tag)
+			Models::PaginatedResponse.new(Models::Player, api.clan_members(tag), self)
+		end
+		
+		def player(tag)
+			Models::Player.new(api.player(tag), self)
 		end
 		
 		def player_verifytoken(player_tag, token)
@@ -20,27 +44,29 @@ module ClashOfClansApi
 			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}."
+				when 'ok'
+					true
+				when 'invalid'
+					false
+				else
+					raise "Unknown status #{response['status'].inspect}."
 			end
 		end
 		
+		def capitalleagues
+			Models::PaginatedResponse.new(Models::CapitalLeague, api.capitalleagues, self)
+		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
+			Models::PaginatedResponse.new(Models::League, api.leagues, self)
+		end
+		
+		def league_season(league_id=29000022, season_id, limit: 10, before: nil, after: nil) # rubocop:disable Style/OptionalArguments
+			Models::PaginatedResponse.new(Models::Player, api.league_season(league_id, season_id, query: {limit: limit, before: before, after: after}.compact), self)
 		end
 		
 		def league(id)
-			Models::League.new(api.league(id))
+			Models::League.new(api.league(id), self)
 		end
 	end
 end

data/lib/clash_of_clans_api/models/achievement.rb

@@ -0,0 +1,15 @@
+require_relative 'base'
+
+module ClashOfClansApi
+	module Models
+		class Achievement < Base
+			property :name,            'name',           required: true
+			property :stars,           'stars',          required: true
+			property :value,           'value',          required: true
+			property :target,          'target',         required: true
+			property :info,            'info',           required: true
+			property :completion_info, 'completionInfo', required: true
+			property :village,         'village',        required: true
+		end
+	end
+end

data/lib/clash_of_clans_api/models/base.rb

@@ -1,10 +1,14 @@
 require_relative 'invalid_data_error'
+require 'date'
 
 module ClashOfClansApi
 	module Models
 		class Base
-			def initialize(hash)
-				@hash = hash
+			attr_reader :client
+			
+			def initialize(hash, client)
+				@hash   = hash
+				@client = client
 				
 				validate!
 			end
@@ -18,52 +22,75 @@ module ClashOfClansApi
 			end
 			
 			class << self
-				attr_reader :required_fields
+				def registered_properties
+					@registered_properties ||= {}
+				end
 				
-				def property(name, key, type: nil, required: false)
-					define_method(name) do
-						if type.nil?
+				def property(method_name, key, type: nil, required: false, default: nil)
+					define_method(method_name) do
+						deduced_type =
+							case type
+								when Symbol
+									send(type)
+								when String
+									self.class.const_get(type)
+								else
+									type
+							end
+						
+						if !@hash.key?(key)
+							default
+						elsif deduced_type.nil?
 							self[key]
+						elsif property_cached?(method_name)
+							property_from_cache(method_name)
 						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)
+							initializer_proc = proc do |item|
+								if deduced_type.ancestors.include?(ClashOfClansApi::Models::Base)
+									deduced_type.new(item, self.client)
+								elsif deduced_type == DateTime
+									DateTime.parse(item)
+								else
+									deduced_type.new(item)
+								end
 							end
+							
+							cache_property(method_name, self[key].then do |prop|
+								prop.is_a?(Array) ? prop.map(&initializer_proc) : initializer_proc.call(prop)
+							end)
 						end
 					end
 					
-					if required
-						@required_fields = (@required_fields || [])+[key]
-					end
+					registered_properties[key] = {
+						method_name: method_name,
+						required:    required,
+						default:     default,
+						type:        type,
+					}
 				end
 			end
 			
-			def property_cached?(name)
-				@property_cache && @property_cache.key?(name)
+			def property_cached?(method_name)
+				@property_cache && @property_cache.key?(method_name)
 			end
 			
-			def cache_property(name, obj)
+			def cache_property(method_name, obj)
 				@property_cache ||= {}
 				
-				@property_cache[name] = obj
+				@property_cache[method_name] = obj
 			end
 			
-			def property_from_cache(name)
-				@property_cache[name]
+			def property_from_cache(method_name)
+				@property_cache[method_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
+				missing = self.class.registered_properties.reject do |field_name, properties|
+					!properties[:required] || @hash.key?(field_name)
+				end
+				
+				if missing.any?
+					raise InvalidDataError, "The following keys are required, but missing from the model data: #{missing.keys.map(&:inspect).join(', ')}"
 				end
 			end
 		end

data/lib/clash_of_clans_api/models/builder_base_league.rb

@@ -0,0 +1,10 @@
+require_relative 'base'
+
+module ClashOfClansApi
+	module Models
+		class BuilderBaseLeague < Base
+			property :id,   'id',   required: true
+			property :name, 'name', required: true
+		end
+	end
+end

data/lib/clash_of_clans_api/models/capital_league.rb

@@ -0,0 +1,10 @@
+require_relative 'base'
+
+module ClashOfClansApi
+	module Models
+		class CapitalLeague < Base
+			property :id,   'id',   required: true
+			property :name, 'name', required: true
+		end
+	end
+end

data/lib/clash_of_clans_api/models/chat_language.rb

@@ -0,0 +1,11 @@
+require_relative 'base'
+
+module ClashOfClansApi
+	module Models
+		class ChatLanguage < Base
+			property :id,            'id',           required: true
+			property :name,          'name',         required: true
+			property :language_code, 'languageCode', required: true
+		end
+	end
+end

data/lib/clash_of_clans_api/models/clan.rb

@@ -0,0 +1,44 @@
+require_relative 'base'
+require_relative 'capital_league'
+require_relative 'chat_language'
+require_relative 'clan_capital'
+require_relative 'clan_location'
+require_relative 'icon_set'
+require_relative 'label'
+require_relative 'war_league'
+
+module ClashOfClansApi
+	module Models
+		class Clan < Base
+			property :tag,                            'tag',  required: true
+			property :name,                           'name', required: true
+			property :type,                           'type'
+			property :description,                    'description'
+			property :location,                       'location',                    type: ClanLocation
+			property :family_friendly?,               'isFamilyFriendly'
+			property :badge_urls,                     'badgeUrls',                   type: IconSet
+			property :clan_level,                     'clanLevel'
+			property :clan_points,                    'clanPoints'
+			property :clan_builder_base_points,       'clanBuilderBasePoints'
+			property :clan_versus_points,             'clanVersusPoints'
+			property :clan_capital_points,            'clanCapitalPoints'
+			property :capital_league,                 'capitalLeague',               type: CapitalLeague
+			property :required_trophies,              'requiredTrophies'
+			property :war_frequency,                  'warFrequency'
+			property :war_win_streak,                 'warWinStreak'
+			property :war_wins,                       'warWins'
+			property :war_ties,                       'warTies'
+			property :war_losses,                     'warLosses'
+			property :war_log_public?,                'isWarLogPublic'
+			property :war_league,                     'warLeague',                   type: WarLeague
+			property :members,                        'members'
+			property :member_list,                    'memberList',                  type: 'ClashOfClansApi::Models::Player'
+			property :labels,                         'labels',                      type: Label
+			property :required_builder_base_trophies, 'requiredBuilderBaseTrophies'
+			property :required_versus_trophies,       'requiredVersusTrophies'
+			property :required_townhall_level,        'requiredTownhallLevel'
+			property :clan_capital,                   'clanCapital',                 type: ClanCapital
+			property :chat_language,                  'chatLanguage',                type: ChatLanguage
+		end
+	end
+end

data/lib/clash_of_clans_api/models/clan_capital.rb

@@ -0,0 +1,11 @@
+require_relative 'base'
+require_relative 'clan_capital_district'
+
+module ClashOfClansApi
+	module Models
+		class ClanCapital < Base
+			property :capital_hall_level, 'capitalHallLevel', required: true
+			property :districts,          'districts',        required: true, type: ClanCapitalDistrict
+		end
+	end
+end

data/lib/clash_of_clans_api/models/clan_capital_district.rb

@@ -0,0 +1,11 @@
+require_relative 'base'
+
+module ClashOfClansApi
+	module Models
+		class ClanCapitalDistrict < Base
+			property :id,                  'id',                required: true
+			property :name,                'name',              required: true
+			property :district_hall_level, 'districtHallLevel', required: true
+		end
+	end
+end

data/lib/clash_of_clans_api/models/clan_location.rb

@@ -0,0 +1,11 @@
+require_relative 'base'
+
+module ClashOfClansApi
+	module Models
+		class ClanLocation < Base
+			property :id,       'id',        required: true
+			property :name,     'name',      required: true
+			property :country?, 'isCountry', required: true
+		end
+	end
+end

data/lib/clash_of_clans_api/models/hero.rb

@@ -0,0 +1,12 @@
+require_relative 'base'
+
+module ClashOfClansApi
+	module Models
+		class Hero < Base
+			property :name,      'name',     required: true
+			property :level,     'level',    required: true
+			property :max_level, 'maxLevel', required: true
+			property :village,   'village',  required: true
+		end
+	end
+end

data/lib/clash_of_clans_api/models/label.rb

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

data/lib/clash_of_clans_api/models/league.rb

@@ -6,7 +6,7 @@ module ClashOfClansApi
 		class League < Base
 			property :id,        'id',       required: true
 			property :name,      'name',     required: true
-			property :icon_urls, 'iconUrls', type: IconSet
+			property :icon_urls, 'iconUrls', required: true, type: IconSet
 		end
 	end
 end

data/lib/clash_of_clans_api/models/legend_season.rb

@@ -0,0 +1,11 @@
+require_relative 'base'
+
+module ClashOfClansApi
+	module Models
+		class LegendSeason < Base
+			property :id,       'id',       required: false
+			property :rank,     'rank',     required: true
+			property :trophies, 'trophies', required: true
+		end
+	end
+end

data/lib/clash_of_clans_api/models/legend_statistics.rb

@@ -0,0 +1,13 @@
+require_relative 'base'
+require_relative 'legend_season'
+
+module ClashOfClansApi
+	module Models
+		class LegendStatistics < Base
+			property :legend_trophies, 'legendTrophies', required: true
+			property :previous_season, 'previousSeason', required: true, type: LegendSeason
+			property :best_season,     'bestSeason',     required: true, type: LegendSeason
+			property :current_season,  'currentSeason',  required: true, type: LegendSeason
+		end
+	end
+end

data/lib/clash_of_clans_api/models/paginated_response.rb

@@ -0,0 +1,19 @@
+require_relative 'base'
+require_relative 'pagination_paging'
+
+module ClashOfClansApi
+	module Models
+		class PaginatedResponse < Base
+			attr_accessor :item_type
+			
+			property :items,  'items',  required: true, type: :item_type
+			property :paging, 'paging', required: true, type: PaginationPaging
+			
+			def initialize(item_type, hash, client)
+				self.item_type = item_type
+				
+				super(hash, client)
+			end
+		end
+	end
+end

data/lib/clash_of_clans_api/models/pagination_cursors.rb

@@ -0,0 +1,10 @@
+require_relative 'base'
+
+module ClashOfClansApi
+	module Models
+		class PaginationCursors < Base
+			property :after,  'after'
+			property :before, 'before'
+		end
+	end
+end

data/lib/clash_of_clans_api/models/pagination_paging.rb

@@ -0,0 +1,10 @@
+require_relative 'base'
+require_relative 'pagination_cursors'
+
+module ClashOfClansApi
+	module Models
+		class PaginationPaging < Base
+			property :cursors, 'cursors', required: true, type: PaginationCursors
+		end
+	end
+end

data/lib/clash_of_clans_api/models/player.rb

@@ -0,0 +1,51 @@
+require_relative 'base'
+require_relative 'achievement'
+require_relative 'builder_base_league'
+require_relative 'hero'
+require_relative 'label'
+require_relative 'league'
+require_relative 'legend_statistics'
+require_relative 'player_house'
+require_relative 'spell'
+require_relative 'troop'
+
+module ClashOfClansApi
+	module Models
+		class Player < Base
+			property :tag,                        'tag',  required: true
+			property :name,                       'name', required: true
+			property :town_hall_level,            'townHallLevel'
+			property :town_hall_weapon_level,     'townHallWeaponLevel'
+			property :exp_level,                  'expLevel'
+			property :trophies,                   'trophies'
+			property :best_trophies,              'bestTrophies'
+			property :war_stars,                  'warStars'
+			property :attack_wins,                'attackWins'
+			property :defense_wins,               'defenseWins'
+			property :builder_hall_level,         'builderHallLevel'
+			property :builder_base_trophies,      'builderBaseTrophies'
+			property :versus_trophies,            'versusTrophies'
+			property :best_builder_base_trophies, 'bestBuilderBaseTrophies'
+			property :best_versus_trophies,       'bestVersusTrophies'
+			property :versus_battle_wins,         'versusBattleWins'
+			property :role,                       'role'
+			property :war_preference,             'warPreference'
+			property :clan_rank,                  'clanRank'
+			property :previous_clan_rank,         'previousClanRank'
+			property :donations,                  'donations'
+			property :donations_received,         'donationsReceived'
+			property :rank,                       'rank'
+			property :clan_capital_contributions, 'clanCapitalContributions'
+			property :clan,                       'clan',              type: 'ClashOfClansApi::Models::Clan'
+			property :league,                     'league',            type: League
+			property :builder_base_league,        'builderBaseLeague', type: BuilderBaseLeague
+			property :legend_statistics,          'legendStatistics',  type: LegendStatistics
+			property :achievements,               'achievements',      type: Achievement
+			property :player_house,               'playerHouse',       type: PlayerHouse
+			property :labels,                     'labels',            type: Label
+			property :troops,                     'troops',            type: Troop
+			property :heroes,                     'heroes',            type: Hero
+			property :spells,                     'spells',            type: Spell
+		end
+	end
+end

data/lib/clash_of_clans_api/models/player_house.rb

@@ -0,0 +1,10 @@
+require_relative 'base'
+require_relative 'player_house_element'
+
+module ClashOfClansApi
+	module Models
+		class PlayerHouse < Base
+			property :elements, 'elements', type: PlayerHouseElement, required: true
+		end
+	end
+end

data/lib/clash_of_clans_api/models/player_house_element.rb

@@ -0,0 +1,10 @@
+require_relative 'base'
+
+module ClashOfClansApi
+	module Models
+		class PlayerHouseElement < Base
+			property :type, 'type', required: true
+			property :id,   'id',   required: true
+		end
+	end
+end

data/lib/clash_of_clans_api/models/spell.rb

@@ -0,0 +1,12 @@
+require_relative 'base'
+
+module ClashOfClansApi
+	module Models
+		class Spell < Base
+			property :name,      'name',     required: true
+			property :level,     'level',    required: true
+			property :max_level, 'maxLevel', required: true
+			property :village,   'village',  required: true
+		end
+	end
+end

data/lib/clash_of_clans_api/models/token.rb

@@ -14,14 +14,8 @@ module ClashOfClansApi
 			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)
+				self.client.revoke_api_key(self.id)
 			end
 			
 			def client_from_token

data/lib/clash_of_clans_api/models/troop.rb

@@ -0,0 +1,13 @@
+require_relative 'base'
+
+module ClashOfClansApi
+	module Models
+		class Troop < Base
+			property :name,                  'name',               required: true
+			property :level,                 'level',              required: true
+			property :max_level,             'maxLevel',           required: true
+			property :village,               'village',            required: true
+			property :super_troop_is_active, 'superTroopIsActive', required: false, default: false
+		end
+	end
+end

data/lib/clash_of_clans_api/models/war.rb

@@ -0,0 +1,18 @@
+require_relative 'base'
+require_relative 'war_clan'
+
+module ClashOfClansApi
+	module Models
+		class War < Base
+			property :state,                  'state'
+			property :result,                 'result'
+			property :start_time,             'startTime',                        type: DateTime
+			property :end_time,               'endTime',                          type: DateTime
+			property :preparation_start_time, 'preparationStartTime',             type: DateTime
+			property :team_size,              'teamSize'
+			property :attacks_per_member,     'attacksPerMember'
+			property :clan,                   'clan',             required: true, type: WarClan
+			property :opponent,               'opponent',         required: true, type: WarClan
+		end
+	end
+end

data/lib/clash_of_clans_api/models/war_attack.rb

@@ -0,0 +1,14 @@
+require_relative 'base'
+
+module ClashOfClansApi
+	module Models
+		class WarAttack < Base
+			property :attacker_tag,           'attackerTag',           required: true
+			property :defender_tag,           'defenderTag',           required: true
+			property :stars,                  'stars',                 required: true
+			property :destruction_percentage, 'destructionPercentage', required: true
+			property :order,                  'order',                 required: true
+			property :duration,               'duration',              required: true
+		end
+	end
+end

data/lib/clash_of_clans_api/models/war_clan.rb

@@ -0,0 +1,19 @@
+require_relative 'base'
+require_relative 'icon_set'
+require_relative 'war_clan_member'
+
+module ClashOfClansApi
+	module Models
+		class WarClan < Base
+			property :tag,                    'tag'
+			property :name,                   'name'
+			property :badge_urls,             'badgeUrls', type: IconSet
+			property :clan_level,             'clanLevel'
+			property :attacks,                'attacks'
+			property :stars,                  'stars'
+			property :destruction_percentage, 'destructionPercentage'
+			property :exp_earned,             'expEarned'
+			property :members,                'members', type: WarClanMember
+		end
+	end
+end

data/lib/clash_of_clans_api/models/war_clan_member.rb

@@ -0,0 +1,16 @@
+require_relative 'base'
+require_relative 'war_attack'
+
+module ClashOfClansApi
+	module Models
+		class WarClanMember < Base
+			property :tag,                  'tag',  required: true
+			property :name,                 'name', required: true
+			property :townhall_level,       'townhallLevel'
+			property :map_position,         'mapPosition'
+			property :attacks,              'attacks',            type: WarAttack
+			property :opponent_attacks,     'opponentAttacks'
+			property :best_opponent_attack, 'bestOpponentAttack', type: WarAttack
+		end
+	end
+end

data/lib/clash_of_clans_api/models/war_league.rb

@@ -0,0 +1,10 @@
+require_relative 'base'
+
+module ClashOfClansApi
+	module Models
+		class WarLeague < Base
+			property :id,   'id',   required: true
+			property :name, 'name', required: true
+		end
+	end
+end

data/lib/clash_of_clans_api/token_api.rb

@@ -1,11 +1,11 @@
-require_relative 'endpoint_methods'
+require 'api_frame'
 
 module ClashOfClansApi
 	module TokenApi
 		BASE_URI = URI('https://developer.clashofclans.com/api/')
 		
 		class << self
-			include EndpointMethods
+			include ApiFrame::EndpointMethods
 			
 			def base_uri
 				BASE_URI

data/lib/clash_of_clans_api/token_client.rb

@@ -36,14 +36,14 @@ module ClashOfClansApi
 			response = TokenApi.apikey_list(headers: @session_headers)
 			
 			response['keys'].map do |key|
-				Models::Token.new(key, token_client: self)
+				Models::Token.new(key, 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)
+			Models::Token.new(response['key'], self)
 		end
 		
 		def revoke_api_key(id)
@@ -52,6 +52,20 @@ module ClashOfClansApi
 			true
 		end
 		
+		def create_or_get_api_key_for_current_ipv4_address(name, description=name, overwrite: false)
+			current_ipv4 = ClashOfClansApi::Utils.current_ipv4_address
+			token        = list_api_keys.select{ |i| i.name == name }.first
+			
+			if token && token.cidr_ranges.include?(current_ipv4)
+				token
+			elsif (token && overwrite) || !token
+				token&.revoke
+				create_api_key(name, description, current_ipv4)
+			else
+				false
+			end
+		end
+		
 		class << self
 			def create!(email, password)
 				new(email, password).login!

data/lib/clash_of_clans_api/utils.rb

@@ -2,32 +2,7 @@ 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
+		def self.current_ipv4_address
 			IPAddr.new(URI('https://ipv4.icanhazip.com').open.read.strip).to_s
 		end
 	end

data/lib/clash_of_clans_api/version.rb

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

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: clash_of_clans_api
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - expeehaa
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-26 00:00:00.000000000 Z
-dependencies: []
+date: 2023-10-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: api_frame
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description:
 email:
 - expeehaa@outlook.com
@@ -21,13 +35,36 @@ files:
 - 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/achievement.rb
 - lib/clash_of_clans_api/models/base.rb
+- lib/clash_of_clans_api/models/builder_base_league.rb
+- lib/clash_of_clans_api/models/capital_league.rb
+- lib/clash_of_clans_api/models/chat_language.rb
+- lib/clash_of_clans_api/models/clan.rb
+- lib/clash_of_clans_api/models/clan_capital.rb
+- lib/clash_of_clans_api/models/clan_capital_district.rb
+- lib/clash_of_clans_api/models/clan_location.rb
+- lib/clash_of_clans_api/models/hero.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/label.rb
 - lib/clash_of_clans_api/models/league.rb
+- lib/clash_of_clans_api/models/legend_season.rb
+- lib/clash_of_clans_api/models/legend_statistics.rb
+- lib/clash_of_clans_api/models/paginated_response.rb
+- lib/clash_of_clans_api/models/pagination_cursors.rb
+- lib/clash_of_clans_api/models/pagination_paging.rb
+- lib/clash_of_clans_api/models/player.rb
+- lib/clash_of_clans_api/models/player_house.rb
+- lib/clash_of_clans_api/models/player_house_element.rb
+- lib/clash_of_clans_api/models/spell.rb
 - lib/clash_of_clans_api/models/token.rb
-- lib/clash_of_clans_api/no_success_error.rb
+- lib/clash_of_clans_api/models/troop.rb
+- lib/clash_of_clans_api/models/war.rb
+- lib/clash_of_clans_api/models/war_attack.rb
+- lib/clash_of_clans_api/models/war_clan.rb
+- lib/clash_of_clans_api/models/war_clan_member.rb
+- lib/clash_of_clans_api/models/war_league.rb
 - lib/clash_of_clans_api/tags.rb
 - lib/clash_of_clans_api/token_api.rb
 - lib/clash_of_clans_api/token_client.rb
@@ -37,6 +74,7 @@ homepage: https://github.com/expeehaa/clash_of_clans_api
 licenses: []
 metadata:
   allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -45,14 +83,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.22
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: Client library for interacting with the ClashOfClans API.

data/lib/clash_of_clans_api/endpoint_methods.rb

@@ -1,68 +0,0 @@
-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/no_success_error.rb

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