clash_of_clans_api 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17f2ed1ae9f529afa9f24bb6ee50bc3f35b70fb420bd972b22feedcf5df185da
-  data.tar.gz: 464de1457dd80505922d87511956aa4db139bf42ac51bea7a73d17d9f9572423
+  metadata.gz: c3406e2ce3f3bf897da83e7a6412a66e692bb76e8df66b83d84a7b3132663af2
+  data.tar.gz: 56b4c3b5d2bcd0fd39dcc80a44182e783c24087442fed953e5f85ab8e221b9f1
 SHA512:
-  metadata.gz: 249a37b6c0fa133af87ef742a7f23ede23fc85264a898f5c32672ff6be0c1099f00d6471a776eca315e09fbeb2ec7e248d466954bdc0cc1cdb03034bc41f7064
-  data.tar.gz: da0f8eca3f5482d89f091eb033f28de91d23f42c031ef5420b328c42dc02ae1cf859e744554c66d8695c0dc89f2454010bce1d7843561b3b8ab6a4a6dec017ed
+  metadata.gz: 451953dbac8d17669134d8cd072425e1f406aa50425b01fc003549a1285337cae130f60831f3294546128cbd717f97255ed0c82372982729f44eeebe0c962d4c
+  data.tar.gz: f098a36f13f7925fc402e38517115610a7e686c1ec431bf60bef177b9acf27dee139b839a88ec898dfac4de6af484c86e9f815b717b5fd71a021838b0c38ddcb

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,46 @@ 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}"}) }
-		
-		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_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 :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

@@ -3,6 +3,7 @@ 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
@@ -16,6 +17,26 @@ module ClashOfClansApi
 			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)
 			response = api.player_verifytoken(player_tag, token: token)
 			
@@ -32,28 +53,20 @@ module ClashOfClansApi
 			end
 		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)
+		def capitalleagues
+			Models::PaginatedResponse.new(Models::CapitalLeague, api.capitalleagues, self)
 		end
 		
 		def leagues
 			Models::PaginatedResponse.new(Models::League, api.leagues, self)
 		end
 		
-		def league(id)
-			Models::League.new(api.league(id), self)
-		end
-		
-		def player(tag)
-			Models::Player.new(api.player(tag), self)
+		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_season(league_id=29000022, season_id, limit: nil, 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)
+		def league(id)
+			Models::League.new(api.league(id), self)
 		end
 	end
 end

data/lib/clash_of_clans_api/models/base.rb

@@ -1,4 +1,5 @@
 require_relative 'invalid_data_error'
+require 'date'
 
 module ClashOfClansApi
 	module Models
@@ -21,11 +22,13 @@ module ClashOfClansApi
 			end
 			
 			class << self
-				attr_reader :required_fields
+				def registered_properties
+					@registered_properties ||= {}
+				end
 				
-				def property(name, key, type: nil, required: false, default: nil)
-					define_method(name) do
-						type =
+				def property(method_name, key, type: nil, required: false, default: nil)
+					define_method(method_name) do
+						deduced_type =
 							case type
 								when Symbol
 									send(type)
@@ -35,56 +38,59 @@ module ClashOfClansApi
 									type
 							end
 						
-						if !@hash.key?(key) && !default.nil?
+						if !@hash.key?(key)
 							default
-						elsif type.nil?
+						elsif deduced_type.nil?
 							self[key]
-						elsif property_cached?(name)
-							property_from_cache(name)
+						elsif property_cached?(method_name)
+							property_from_cache(method_name)
 						else
 							initializer_proc = proc do |item|
-								if type.ancestors.include?(ClashOfClansApi::Models::Base)
-									type.new(item, self.client)
+								if deduced_type.ancestors.include?(ClashOfClansApi::Models::Base)
+									deduced_type.new(item, self.client)
+								elsif deduced_type == DateTime
+									DateTime.parse(item)
 								else
-									type.new(item)
+									deduced_type.new(item)
 								end
 							end
 							
-							cache_property(name, self[key].then do |prop|
+							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

@@ -1,32 +1,42 @@
 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 :clan_level,               'clanLevel',              required: true
-			property :badge_urls,               'badgeUrls',              required: true, type: IconSet
-			property :type,                     'type'
-			property :location,                 'location'
-			property :clan_points,              'clanPoints'
-			property :clan_versus_points,       'clanVersusPoints'
-			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 :is_war_log_public,        'isWarLogPublic'
-			property :war_league,               'warLeague'
-			property :members,                  'members'
-			property :member_list,              'memberList',             type: 'ClashOfClansApi::Models::Player'
-			property :labels,                   'labels',                 type: Label
-			property :chat_language,            'chatLanguage'
-			property :required_versus_trophies, 'requiredVersusTrophies'
-			property :required_townhall_level,  'requiredTownhallLevel'
+			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_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_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

@@ -1,4 +1,5 @@
 require_relative 'base'
+require_relative 'hero_equipment'
 
 module ClashOfClansApi
 	module Models
@@ -7,6 +8,7 @@ module ClashOfClansApi
 			property :level,     'level',    required: true
 			property :max_level, 'maxLevel', required: true
 			property :village,   'village',  required: true
+			property :equipment, 'equipment', type: HeroEquipment
 		end
 	end
 end

data/lib/clash_of_clans_api/models/hero_equipment.rb

@@ -0,0 +1,12 @@
+require_relative 'base'
+
+module ClashOfClansApi
+	module Models
+		class HeroEquipment < 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/paginated_response.rb

@@ -1,12 +1,13 @@
 require_relative 'base'
+require_relative 'pagination_paging'
 
 module ClashOfClansApi
 	module Models
 		class PaginatedResponse < Base
 			attr_accessor :item_type
 			
-			property :items,  'items',  type: :item_type, required: true
-			property :paging, 'paging'
+			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

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

@@ -1,43 +1,50 @@
 require_relative 'base'
 require_relative 'achievement'
+require_relative 'builder_base_league'
 require_relative 'hero'
+require_relative 'hero_equipment'
 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',             required: true
-			property :best_trophies,           'bestTrophies'
-			property :war_stars,               'warStars'
-			property :attack_wins,             'attackWins'
-			property :defense_wins,            'defenseWins'
-			property :builder_hall_level,      'builderHallLevel'
-			property :versus_trophies,         'versusTrophies'
-			property :best_versus_trophies,    'bestVersusTrophies'
-			property :versus_battle_wins,      'versusBattleWins'
-			property :role,                    'role'
-			property :war_preference,          'warPreference'
-			property :donations,               'donations'
-			property :donations_received,      'donationsReceived'
-			property :rank,                    'rank'
-			property :clan,                    'clan',                 type: 'ClashOfClansApi::Models::Clan'
-			property :league,                  'league',               type: League
-			property :legend_statistics,       'legendStatistics',     type: LegendStatistics
-			property :achievements,            'achievements',         type: Achievement
-			property :versus_battle_win_count, 'versusBattleWinCount'
-			property :labels,                  'labels',               type: Label
-			property :troops,                  'troops',               type: Troop
-			property :heroes,                  'heroes',               type: Hero
-			property :spells,                  'spells',               type: Spell
+			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 :best_builder_base_trophies, 'bestBuilderBaseTrophies'
+			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
+			property :hero_equipment,             'heroEquipment',     type: HeroEquipment
 		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/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

@@ -21,7 +21,7 @@ module ClashOfClansApi
 						'Cookie' => "session=#{cookies['session'][0]}",
 					}
 				else
-					raise NoSuccessError, response
+					raise ApiFrame::NoSuccessError, response
 				end
 			end
 		end
@@ -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,31 +2,6 @@ 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.current_ipv4_address
 			IPAddr.new(URI('https://ipv4.icanhazip.com').open.read.strip).to_s
 		end

data/lib/clash_of_clans_api/version.rb

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

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: clash_of_clans_api
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - expeehaa
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-02-13 00:00:00.000000000 Z
-dependencies: []
+date: 2023-12-26 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,11 +35,17 @@ 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/hero_equipment.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
@@ -33,11 +53,19 @@ files:
 - 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/models/troop.rb
-- lib/clash_of_clans_api/no_success_error.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
@@ -56,14 +84,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+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,67 +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, 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.key?(:query) ? kwargs.fetch(:query) : nil, headers: kwargs.key?(:headers) ? kwargs.fetch(:headers) : nil).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,11 +0,0 @@
-module ClashOfClansApi
-	class NoSuccessError < StandardError
-		attr_reader :response
-		
-		def initialize(response)
-			super
-			
-			@response = response
-		end
-	end
-end