fotmob 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5caec733f122382ab9f85603b76e3bbe504b30441006fd45cffda22fbe3ef7a
-  data.tar.gz: 03b13331563a2a684bae0f24c332969b83a6b2abbce004777747758fca0dcd59
+  metadata.gz: fc5115b39ae5263043d1efc3a66205b9e005c978c442d7aa9c246065b80fdbfb
+  data.tar.gz: 02461ba1b0750f0614df5ad2baf18eba734deb810da9a6f99619c0dfa61fefe0
 SHA512:
-  metadata.gz: a4568898b296b09d8984c40165568ea18cdbe0f60f54a0e4d5b1d01db6291f8962785128b24f40cc76553529b17a58a50ebf45e86aad7663cdcce6a827f6ab66
-  data.tar.gz: 4f6e2475ae2e1c029990de8d332b4eec869367adace09e315238452fee8427a81781eadc4a21d2513b6212807b44ebdb04753785c95a528590bc2254a7f04f2b
+  metadata.gz: 0cfe6fc4a515cb3ef0431a3c7d62ce94227c2c4eb78d925489e2051e1f8fe3b0af84ad399a845272860e5449a868e991e54058dc6a6393934fbf9c2d8e3ca000
+  data.tar.gz: 82c1c31b13f588eff307b5283f1b6fb9c571bf2ae5e3844f6feb0a296fd51bcbff9940aff9f185d6a4c939be76f3fe62c9a65ed05eed8004c1fcde7c7cc55901

data/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-01-15
+
+### Changed
+- Version bump for first stable release
+- Repository cleanup (removed build artifacts and test files)
+- Added MIT LICENSE file
+- Added CI status badge to README
+
+## [0.0.1] - 2026-01-15
+
+### Added
+- Initial release of modernized fotmob gem
+- Modern project structure with separate modules
+- Custom error classes (Error, APIError, NotFoundError, RateLimitError, TimeoutError, InvalidResponseError)
+- URI.open-based HTTP client with timeout support
+- Comprehensive error handling with proper HTTP status codes
+- YARD documentation for all public methods
+- RSpec test suite with VCR for API response recording
+- RuboCop linting with sensible defaults
+- GitHub Actions CI for automated testing
+- Gemfile and Rakefile for development workflow
+- Comprehensive README with examples and badges
+
+### Changed
+- Refactored from single-file to modular structure
+- Improved from basic API wrapper to production-ready gem
+- Switched to symbolized JSON keys for better Ruby idioms
+- Added timeout configuration support
+
+### API Methods
+- `get_team(team_id)` - Get team information and statistics
+- `get_match_details(match_id)` - Get detailed match information
+- `get_player(player_id)` - Get player profile and stats
+- `get_league(league_id)` - Get league standings and details
+- `get_matches(date)` - Get matches by date (limited availability)
+
+### Technical Details
+- Requires Ruby >= 2.7.0
+- Uses standard library only (no runtime dependencies)
+- Tested on Ruby 2.7, 3.0, 3.1, 3.2, 3.3
+- Bot protection handling via URI.open
+- Configurable timeout (default: 10 seconds)
+
+### Known Limitations
+- `get_matches` endpoint requires special authentication headers and may not work reliably
+- API is unofficial and may change without notice
+
+[0.0.1]: https://github.com/bjrsti/fotmob/releases/tag/v0.0.1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stian Bjørkelo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,209 @@
+# Fotmob Ruby Gem
+
+[![Gem Version](https://badge.fury.io/rb/fotmob.svg)](https://badge.fury.io/rb/fotmob)
+[![CI](https://github.com/bjrsti/fotmob/actions/workflows/ci.yml/badge.svg)](https://github.com/bjrsti/fotmob/actions/workflows/ci.yml)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.7-ruby.svg)](https://www.ruby-lang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+An unofficial Ruby wrapper for the [FotMob](https://www.fotmob.com/) API. Get football/soccer data including team stats, match details, player information, and league standings.
+
+## Features
+
+- 🏆 **Team Data** - Get comprehensive team information and statistics
+- ⚽ **Match Details** - Detailed match information and live scores
+- 👤 **Player Stats** - Player profiles and performance data
+- 📊 **League Standings** - League tables and competition data
+- 🛡️ **Error Handling** - Custom error classes for different scenarios
+- ⏱️ **Timeout Support** - Configurable request timeouts
+- 📝 **Well Documented** - YARD documentation included
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'fotmob'
+```
+
+Or install directly:
+
+```bash
+gem install fotmob
+```
+
+## Quick Start
+
+```ruby
+require 'fotmob'
+
+# Create a client
+client = Fotmob.new
+
+# Get team information
+team = client.get_team("8540") # Palermo
+puts team[:details][:name]
+
+# Get match details
+match = client.get_match_details("4193741")
+puts "#{match[:general][:homeTeam][:name]} vs #{match[:general][:awayTeam][:name]}"
+
+# Get player data
+player = client.get_player("961995") # Mbappé
+puts player[:name]
+
+# Get league standings
+league = client.get_league("47") # Premier League
+puts league[:details][:name]
+```
+
+## API Methods
+
+### `get_team(team_id)`
+
+Get comprehensive team information.
+
+```ruby
+team = client.get_team("8540")
+# Returns: Hash with team details, fixtures, squad, etc.
+```
+
+### `get_match_details(match_id)`
+
+Get detailed match information.
+
+```ruby
+match = client.get_match_details("4193741")
+# Returns: Hash with match details, lineups, events, stats
+```
+
+### `get_player(player_id)`
+
+Get player profile and statistics.
+
+```ruby
+player = client.get_player("961995")
+# Returns: Hash with player info and stats
+```
+
+### `get_league(league_id)`
+
+Get league/competition information.
+
+```ruby
+league = client.get_league("47")
+# Returns: Hash with league details and standings
+```
+
+### `get_matches(date)` ⚠️
+
+**Note:** This endpoint currently requires special authentication headers and may not work reliably.
+
+```ruby
+matches = client.get_matches("20250114")
+# Returns: Hash with matches for the specified date
+```
+
+## Configuration
+
+### Custom Timeout
+
+```ruby
+# Default timeout is 10 seconds
+client = Fotmob.new(timeout: 30)
+```
+
+## Error Handling
+
+The gem includes custom error classes for different scenarios:
+
+```ruby
+begin
+  team = client.get_team("invalid_id")
+rescue Fotmob::NotFoundError => e
+  puts "Team not found: #{e.message}"
+rescue Fotmob::RateLimitError => e
+  puts "Rate limit exceeded: #{e.message}"
+rescue Fotmob::TimeoutError => e
+  puts "Request timed out: #{e.message}"
+rescue Fotmob::APIError => e
+  puts "API error: #{e.message} (Status: #{e.status_code})"
+rescue Fotmob::Error => e
+  puts "Error: #{e.message}"
+end
+```
+
+### Error Classes
+
+- `Fotmob::Error` - Base error class
+- `Fotmob::APIError` - API returned an error response
+- `Fotmob::NotFoundError` - Resource not found (404)
+- `Fotmob::RateLimitError` - Rate limit exceeded (429)
+- `Fotmob::TimeoutError` - Request timed out
+- `Fotmob::InvalidResponseError` - Invalid JSON response
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/bjrsti/fotmob.git
+cd fotmob
+
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run linter
+bundle exec rubocop
+
+# Open console
+bundle exec rake console
+```
+
+## Testing
+
+The gem uses RSpec for testing with VCR for recording API responses:
+
+```bash
+bundle exec rspec
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a Pull Request
+
+## Finding IDs
+
+To use the API, you need IDs for teams, players, matches, and leagues:
+
+- **Teams**: Visit [fotmob.com](https://www.fotmob.com/), search for a team, the ID is in the URL
+  - Example: `fotmob.com/teams/8540/overview/palermo` → Team ID: `8540`
+- **Players**: Search for a player, ID is in the URL
+  - Example: `fotmob.com/players/961995/kylian-mbappe` → Player ID: `961995`
+- **Matches**: Browse matches, ID is in the match URL
+  - Example: `fotmob.com/match/4193741` → Match ID: `4193741`
+- **Leagues**: Browse leagues, ID is in the league URL
+  - Example: `fotmob.com/leagues/47/overview/premier-league` → League ID: `47`
+
+## Disclaimer
+
+This is an unofficial API wrapper and is not affiliated with FotMob. Use at your own risk and be mindful of rate limits.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+## Author
+
+[Stian Bjørkelo](https://github.com/bjrsti)
+
+## Links
+
+- [RubyGems](https://rubygems.org/gems/fotmob)
+- [GitHub](https://github.com/bjrsti/fotmob)
+- [Issues](https://github.com/bjrsti/fotmob/issues)

data/lib/fotmob/client.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "open-uri"
+require "json"
+require "uri"
+require "timeout"
+
+module Fotmob
+  # Main client for interacting with the FotMob API
+  class Client
+    BASE_URL = "http://www.fotmob.com/api"
+    DEFAULT_TIMEOUT = 10 # seconds
+
+    attr_reader :timeout
+
+    # Initialize a new FotMob API client
+    #
+    # @param timeout [Integer] Request timeout in seconds (default: 10)
+    def initialize(timeout: DEFAULT_TIMEOUT)
+      @timeout = timeout
+    end
+
+    # Get league/competition data
+    #
+    # @param league_id [String] The league ID
+    # @return [Hash] League data with symbolized keys
+    # @raise [Fotmob::Error] If the request fails
+    def get_league(league_id)
+      get("/leagues", id: league_id)
+    end
+
+    # Get matches for a specific date
+    #
+    # @param date [String] Date in YYYYMMDD format (e.g., "20221030")
+    # @return [Hash] Match data with symbolized keys
+    # @raise [Fotmob::Error] If the request fails
+    def get_matches(date)
+      get("/matches", date: date)
+    end
+
+    # Get detailed information about a specific match
+    #
+    # @param match_id [String] The match ID
+    # @return [Hash] Match details with symbolized keys
+    # @raise [Fotmob::Error] If the request fails
+    def get_match_details(match_id)
+      get("/matchDetails", matchId: match_id)
+    end
+
+    # Get player data and statistics
+    #
+    # @param player_id [String] The player ID
+    # @return [Hash] Player data with symbolized keys
+    # @raise [Fotmob::Error] If the request fails
+    def get_player(player_id)
+      get("/playerData", id: player_id)
+    end
+
+    # Get team data and statistics
+    #
+    # @param team_id [String] The team ID
+    # @return [Hash] Team data with symbolized keys
+    # @raise [Fotmob::Error] If the request fails
+    def get_team(team_id)
+      get("/teams", id: team_id)
+    end
+
+    private
+
+    # Make a GET request to the FotMob API
+    #
+    # @param path [String] API endpoint path
+    # @param params [Hash] Query parameters
+    # @return [Hash] Parsed JSON response with symbolized keys
+    # @raise [Fotmob::Error] If the request fails
+    def get(path, **params)
+      uri = build_uri(path, params)
+      response_body = fetch_with_timeout(uri)
+      parse_json(response_body)
+    rescue OpenURI::HTTPError => e
+      handle_http_error(e)
+    end
+
+    # Build URI with query parameters
+    def build_uri(path, params)
+      # Use string concatenation like old version - URI.join doesn't work with /api/path
+      url = BASE_URL + path
+      uri = URI(url)
+      uri.query = URI.encode_www_form(params) unless params.empty?
+      uri
+    end
+
+    # Fetch URL with timeout using URI.open (avoids bot detection)
+    def fetch_with_timeout(uri)
+      Timeout.timeout(@timeout) do
+        URI.open(uri.to_s).read
+      end
+    rescue Timeout::Error => e
+      raise TimeoutError, "Request timed out after #{@timeout} seconds: #{e.message}"
+    rescue OpenURI::HTTPError
+      # Let HTTP errors bubble up to be handled by the caller
+      raise
+    rescue StandardError => e
+      raise Error, "Network error: #{e.message}"
+    end
+
+    # Handle HTTP errors from URI.open
+    def handle_http_error(error)
+      status = error.io.status[0].to_i
+      body = begin
+        error.io.read
+      rescue StandardError
+        ""
+      end
+
+      case status
+      when 404
+        raise NotFoundError.new(
+          "Resource not found",
+          status_code: 404,
+          response_body: body
+        )
+      when 429
+        raise RateLimitError.new(
+          "Rate limit exceeded. Please try again later.",
+          status_code: 429,
+          response_body: body
+        )
+      when 400..499
+        raise APIError.new(
+          "Client error: #{status}",
+          status_code: status,
+          response_body: body
+        )
+      when 500..599
+        raise APIError.new(
+          "Server error: #{status}",
+          status_code: status,
+          response_body: body
+        )
+      else
+        raise APIError.new(
+          "HTTP Error: #{status}",
+          status_code: status,
+          response_body: body
+        )
+      end
+    end
+
+    # Parse JSON response with symbolized keys
+    def parse_json(body)
+      JSON.parse(body, symbolize_names: true)
+    rescue JSON::ParserError => e
+      raise InvalidResponseError, "Failed to parse response: #{e.message}"
+    end
+  end
+end

data/lib/fotmob/error.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Fotmob
+  # Base error class for all Fotmob errors
+  class Error < StandardError; end
+
+  # Raised when the API returns an error response
+  class APIError < Error
+    attr_reader :status_code, :response_body
+
+    def initialize(message, status_code: nil, response_body: nil)
+      @status_code = status_code
+      @response_body = response_body
+      super(message)
+    end
+  end
+
+  # Raised when a resource is not found (404)
+  class NotFoundError < APIError; end
+
+  # Raised when rate limit is exceeded (429)
+  class RateLimitError < APIError; end
+
+  # Raised when the request times out
+  class TimeoutError < Error; end
+
+  # Raised when the response cannot be parsed or is invalid
+  class InvalidResponseError < Error; end
+end

data/lib/fotmob/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Fotmob
+  VERSION = "0.1.0"
+end

data/lib/fotmob.rb

@@ -1,45 +1,18 @@
-require 'open-uri'
-require 'json'
+# frozen_string_literal: true
 
-class Fotmob
-  
-  BASE_URL          = "http://www.fotmob.com/api"
-  LEAGUES_URL       = BASE_URL + "/leagues?id="
-  MATCHES_URL       = BASE_URL + "/matches?date="
-  MATCH_DETAILS_URL = BASE_URL + "/matchDetails?matchId="
-  PLAYER_URL        = BASE_URL + "/playerData?id="
-  TEAMS_URL         = BASE_URL + "/teams?id="
-  
-  def get_league(league_id)
-    json = URI.open(LEAGUES_URL+league_id).read
-    symbolize_json(json)
-  end
-  
-  def get_matches(match_date)
-    json = URI.open(MATCHES_URL+match_date).read
-    symbolize_json(json)
-  end
-  
-  def get_match_details(match_id)
-    json = URI.open(MATCH_DETAILS_URL+match_id).read
-    symbolize_json(json)
-  end
-  
-  def get_player(player_id)
-    json = URI.open(PLAYER_URL+player_id).read
-    symbolize_json(json)
-  end
-  
-  def get_team(team_id)
-    json = URI.open(TEAMS_URL+team_id).read
-    symbolize_json(json)
-  end
-  
-  
-  private
-  
-  def symbolize_json(json)
-    JSON.parse(json, :symbolize_names => true)
+require_relative "fotmob/version"
+require_relative "fotmob/error"
+require_relative "fotmob/client"
+
+# FotMob API wrapper for Ruby
+module Fotmob
+  class << self
+    # Create a new client instance
+    #
+    # @param options [Hash] Client options
+    # @return [Fotmob::Client] A new client instance
+    def new(**options)
+      Client.new(**options)
+    end
   end
-  
-end
+end

metadata

@@ -1,67 +1,108 @@
 --- !ruby/object:Gem::Specification
 name: fotmob
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Stian Bjørkelo
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-10-30 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: open-uri
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.2.0
-  type: :runtime
+        version: '13.0'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
-    - - ">="
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
 - !ruby/object:Gem::Dependency
-  name: json
+  name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.6'
-    - - ">="
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.6.2
-  type: :runtime
+        version: '1.50'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.6'
-    - - ">="
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.6.2
-description: Lets you pull data from fotmob for easy access
+        version: '3.18'
+description: A simple Ruby gem for accessing football/soccer data from the FotMob
+  API. Get team stats, match details, player data, league tables, and more.
 email: stianbj@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
+- README.md
 - lib/fotmob.rb
+- lib/fotmob/client.rb
+- lib/fotmob/error.rb
+- lib/fotmob/version.rb
 homepage: https://github.com/bjrsti/fotmob
 licenses:
 - MIT
-metadata: {}
-post_install_message:
+metadata:
+  homepage_uri: https://github.com/bjrsti/fotmob
+  source_code_uri: https://github.com/bjrsti/fotmob
+  bug_tracker_uri: https://github.com/bjrsti/fotmob/issues
+  changelog_uri: https://github.com/bjrsti/fotmob/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/bjrsti/fotmob#readme
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -69,15 +110,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.24
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
-summary: An unofficial Fotmob API wrapper for Ruby
+summary: An unofficial FotMob API wrapper for Ruby
 test_files: []