jikanrb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 322781c4fbc3373799633c17b00a1db8d7c0862e123d0cbade697542c30efbb0
+  data.tar.gz: e63b3b3bccd110e0a234beab9304c5eac563163b8885aa8bf91d403fd212fdaf
+SHA512:
+  metadata.gz: 9ed79ea3b2baa1f643d3e4369a34afad14da572ed36ba9dd5cc2176691f194e305dadecd5e7a40a663e8d32c9d0630eb6c4ff1e7c1fc288280a16bf8c4389c38
+  data.tar.gz: ecfc01bce3b8f605d221508b9a803fa1f0febd5719cef1c7d4c51c040e586dca194d4462792fc85459584371f1ac342b06852f774adcfbd80832a74cceca5fca

data/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(rubocop:*)",
+      "Bash(bundle exec rubocop:*)"
+    ]
+  }
+}

data/.ruby-version

@@ -0,0 +1 @@
+3.1.0

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-01-08
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"jikanrb" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["sergiobrocos@gmail.com"](mailto:"sergiobrocos@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Sergio Brocos
+
+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,202 @@
+# Jikanrb
+
+[![Gem Version](https://badge.fury.io/rb/jikanrb.svg)](https://badge.fury.io/rb/jikanrb)
+[![CI](https://github.com/tuusuario/jikanrb/actions/workflows/main.yml/badge.svg)](https://github.com/tuusuario/jikanrb/actions)
+
+A modern Ruby client for the [Jikan API v4](https://jikan.moe/) - the unofficial MyAnimeList API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'jikanrb'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself:
+
+```bash
+gem install jikanrb
+```
+
+## Usage
+
+### Quick Start
+
+```ruby
+require 'jikanrb'
+
+# Get anime by ID
+anime = Jikanrb.anime(1)
+
+# Access data using strings or symbols (Indifferent Access)
+puts anime["data"]["title"] # => "Cowboy Bebop"
+puts anime[:data][:title]   # => "Cowboy Bebop"
+
+# Get full anime info (includes relations, theme songs, etc.)
+anime = Jikanrb.anime(1, full: true)
+
+# Search anime
+results = Jikanrb.search_anime("Naruto")
+results[:data].each do |anime|
+  puts "#{anime[:title]} - Score: #{anime[:score]}"
+end
+```
+
+### Using a Client Instance
+
+```ruby
+client = Jikanrb::Client.new do |config|
+  config.read_timeout = 15
+  config.max_retries = 5
+end
+
+# All methods available
+client.anime(1)
+client.manga(1)
+client.character(1)
+client.person(1)
+client.search_anime("One Piece", type: "tv", status: "airing")
+client.top_anime(type: "tv", filter: "bypopularity")
+client.season(2024, "winter")
+client.season_now
+client.schedules(day: "monday")
+```
+
+### Configuration in Rails
+
+You can configure the gem globally in an initializer (e.g., `config/initializers/jikanrb.rb`):
+
+```ruby
+# config/initializers/jikanrb.rb
+Jikanrb.configure do |config|
+  config.read_timeout = 20
+  config.max_retries = 3
+  # config.logger = Rails.logger # Use Rails logger
+end
+```
+
+### Global Configuration
+
+```ruby
+Jikanrb.configure do |config|
+  config.base_url = "https://api.jikan.moe/v4"   # Default
+  config.open_timeout = 5                        # Connection timeout (seconds)
+  config.read_timeout = 10                       # Read timeout (seconds)
+  config.max_retries = 3                         # Retry on rate limit/server errors
+  config.retry_interval = 1                      # Initial retry delay (seconds)
+  config.logger = Logger.new($stdout)            # Optional logging
+end
+```
+
+### Available Methods
+
+| Method | Description |
+| :--- | :--- |
+| `anime(id, full: false)` | Get anime by MAL ID |
+| `manga(id, full: false)` | Get manga by MAL ID |
+| `character(id, full: false)` | Get character by MAL ID |
+| `person(id, full: false)` | Get person by MAL ID |
+| `search_anime(query, **params)` | Search anime |
+| `search_manga(query, **params)` | Search manga |
+| `top_anime(type:, filter:, page:)` | Top anime list |
+| `top_manga(type:, filter:, page:)` | Top manga list |
+| `season(year, season, page:)` | Anime by season |
+| `season_now(page:)` | Current season anime |
+| `schedules(day:)` | Weekly schedule |
+
+### Error Handling
+
+```ruby
+begin
+  anime = Jikanrb.anime(999999999)
+rescue Jikanrb::NotFoundError => e
+  puts "Anime not found: #{e.message}"
+rescue Jikanrb::RateLimitError => e
+  puts "Rate limited! Retry after #{e.retry_after} seconds"
+rescue Jikanrb::ConnectionError => e
+  puts "Connection failed: #{e.message}"
+rescue Jikanrb::Error => e
+  puts "Something went wrong: #{e.message}"
+end
+```
+
+### Pagination
+
+The gem provides convenient pagination helpers for working with paginated endpoints:
+
+```ruby
+# Automatic pagination - iterates through all pages
+client = Jikanrb::Client.new
+paginator = client.paginate(:top_anime, type: 'tv')
+
+# Get all items (will fetch all pages)
+all_anime = paginator.all
+
+# Iterate through all pages lazily
+paginator.each do |anime|
+  puts "#{anime['title']} - Score: #{anime['score']}"
+end
+
+# Get items from first 3 pages only
+first_three_pages = paginator.take_pages(3)
+
+# Manual pagination with pagination info
+response = client.top_anime(page: 1)
+pagination = client.pagination_info(response)
+
+puts "Current page: #{pagination.current_page}"
+puts "Total pages: #{pagination.total_pages}"
+puts "Items per page: #{pagination.per_page}"
+puts "Has next page: #{pagination.has_next_page?}"
+puts "Has previous page: #{pagination.has_previous_page?}"
+puts "Next page number: #{pagination.next_page}" if pagination.has_next_page?
+```
+
+### Rate Limiting
+
+Jikan API allows **60 requests per minute**. This gem includes automatic retry with exponential backoff for rate limit errors (429).
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+### Useful Commands
+
+```bash
+# Install dependencies
+bin/setup
+
+# Run tests
+bundle exec rspec
+
+# Interactive console
+bin/console
+
+# Linting
+bundle exec rubocop
+```
+
+## Acknowledgments
+
+This gem is inspired by [jikan.rb](https://github.com/Zerocchi/jikan.rb) by Zerocchi, which wrapped the Jikan API v3.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at <https://github.com/[USERNAME]/jikanrb>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/jikanrb/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Jikanrb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/jikanrb/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/jikanrb/client.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/retry'
+require 'json'
+
+module Jikanrb
+  # Main HTTP client for interacting with the Jikan API v4.
+  # Handles requests, rate limiting, retries, and error handling.
+  #
+  # @example Basic usage
+  #   client = Jikanrb::Client.new
+  #   anime = client.anime(1)
+  #
+  # @example With custom configuration
+  #   client = Jikanrb::Client.new do |config|
+  #     config.read_timeout = 15
+  #     config.max_retries = 5
+  #   end
+  class Client
+    attr_reader :config
+
+    # Initializes the client with optional configuration
+    #
+    # @example With default configuration
+    #   client = Jikanrb::Client.new
+    #
+    # @example With custom configuration
+    #   client = Jikanrb::Client.new do |config|
+    #     config.base_url = "https://api.jikan.moe/v4"
+    #     config.read_timeout = 15
+    #   end
+    #
+    # @yield [config] Optional block to configure the client
+    # @yieldparam config [Configuration] Configuration object
+    def initialize
+      @config = Configuration.new
+      yield(@config) if block_given?
+    end
+
+    # Performs a GET request
+    #
+    # @param path [String] Endpoint path (e.g., "/anime/1")
+    # @param params [Hash] Query string parameters
+    # @return [Hash] Response parsed as Hash
+    def get(path, params = {})
+      request(:get, path, params)
+    end
+
+    # Anime information by ID
+    #
+    # @param id [Integer] Anime ID on MyAnimeList
+    # @param full [Boolean] If true, returns extended information
+    # @return [Hash] Anime data
+    def anime(id, full: false)
+      path = full ? "/anime/#{id}/full" : "/anime/#{id}"
+      get(path)
+    end
+
+    # Manga information by ID
+    #
+    # @param id [Integer] Manga ID on MyAnimeList
+    # @param full [Boolean] If true, returns extended information
+    # @return [Hash] Manga data
+    def manga(id, full: false)
+      path = full ? "/manga/#{id}/full" : "/manga/#{id}"
+      get(path)
+    end
+
+    # Character information by ID
+    #
+    # @param id [Integer] Character ID on MyAnimeList
+    # @param full [Boolean] If true, returns extended information
+    # @return [Hash] Character data
+    def character(id, full: false)
+      path = full ? "/characters/#{id}/full" : "/characters/#{id}"
+      get(path)
+    end
+
+    # Person information by ID
+    #
+    # @param id [Integer] Person ID on MyAnimeList
+    # @param full [Boolean] If true, returns extended information
+    # @return [Hash] Person data
+    def person(id, full: false)
+      path = full ? "/people/#{id}/full" : "/people/#{id}"
+      get(path)
+    end
+
+    # Search anime
+    #
+    # @param query [String] Search term
+    # @param params [Hash] Additional filters (type, score, status, etc.)
+    # @return [Hash] Search results
+    def search_anime(query, **params)
+      get('/anime', params.merge(q: query))
+    end
+
+    # Search manga
+    #
+    # @param query [String] Search term
+    # @param params [Hash] Additional filters
+    # @return [Hash] Search results
+    def search_manga(query, **params)
+      get('/manga', params.merge(q: query))
+    end
+
+    # Top anime
+    #
+    # @param type [String, nil] Filter: "tv", "movie", "ova", etc.
+    # @param filter [String, nil] Filter: "airing", "upcoming", "bypopularity", etc.
+    # @param page [Integer] Page number
+    # @return [Hash] List of top anime
+    def top_anime(type: nil, filter: nil, page: 1)
+      params = { page: page }
+      params[:type] = type if type
+      params[:filter] = filter if filter
+      get('/top/anime', params)
+    end
+
+    # Top manga
+    #
+    # @param type [String, nil] Filter: "manga", "novel", "lightnovel", etc.
+    # @param filter [String, nil] Filter: "publishing", "upcoming", "bypopularity", etc.
+    # @param page [Integer] Page number
+    # @return [Hash] List of top manga
+    def top_manga(type: nil, filter: nil, page: 1)
+      params = { page: page }
+      params[:type] = type if type
+      params[:filter] = filter if filter
+      get('/top/manga', params)
+    end
+
+    # Seasonal anime
+    #
+    # @param year [Integer] Year
+    # @param season [String] Season: "winter", "spring", "summer", "fall"
+    # @param page [Integer] Page number
+    # @return [Hash] Seasonal anime
+    def season(year, season, page: 1)
+      get("/seasons/#{year}/#{season}", page: page)
+    end
+
+    # Current season
+    #
+    # @param page [Integer] Page number
+    # @return [Hash] Current season anime
+    def season_now(page: 1)
+      get('/seasons/now', page: page)
+    end
+
+    # Weekly schedule
+    #
+    # @param day [String, nil] Day: "monday", "tuesday", etc.
+    # @return [Hash] Anime schedule
+    def schedules(day: nil)
+      path = day ? "/schedules/#{day}" : '/schedules'
+      get(path)
+    end
+
+    # Create a paginator for iterating through all pages of a paginated endpoint
+    #
+    # @param method [Symbol] Method name to paginate (e.g., :top_anime, :search_anime)
+    # @param params [Hash] Parameters to pass to the method
+    # @return [Pagination::Paginator] Paginator instance
+    #
+    # @example Iterate through all top anime
+    #   client.paginate(:top_anime, type: 'tv').each do |anime|
+    #     puts anime['title']
+    #   end
+    #
+    # @example Get all items as array
+    #   all_anime = client.paginate(:search_anime, 'Naruto').all
+    #
+    # @example Get first 3 pages only
+    #   anime = client.paginate(:top_anime).take_pages(3)
+    def paginate(method, **params)
+      Pagination::Paginator.new(self, method, **params)
+    end
+
+    # Extract pagination information from a response
+    #
+    # @param response [Hash] API response with pagination data
+    # @return [Pagination::PaginationInfo] Pagination information
+    #
+    # @example
+    #   result = client.top_anime(page: 1)
+    #   pagination = client.pagination_info(result)
+    #   puts "Page #{pagination.current_page} of #{pagination.total_pages}"
+    def pagination_info(response)
+      Pagination::PaginationInfo.new(response)
+    end
+
+    private
+
+    # Faraday connection with configuration
+    def connection
+      @connection ||= Faraday.new(url: config.base_url) do |f|
+        configure_connection_options(f)
+        configure_connection_headers(f)
+        configure_connection_middleware(f)
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    # Configures connection timeouts
+    def configure_connection_options(faraday)
+      faraday.options.open_timeout = config.open_timeout
+      faraday.options.timeout = config.read_timeout
+    end
+
+    # Configures connection headers
+    def configure_connection_headers(faraday)
+      faraday.headers['User-Agent'] = config.user_agent
+      faraday.headers['Accept'] = 'application/json'
+    end
+
+    # Configures retry middleware and logger
+    def configure_connection_middleware(faraday)
+      configure_retry_middleware(faraday)
+      faraday.response :logger, config.logger if config.logger
+    end
+
+    # Configures retry middleware for rate limiting and transient errors
+    def configure_retry_middleware(faraday)
+      faraday.request :retry,
+                      max: config.max_retries,
+                      interval: config.retry_interval,
+                      interval_randomness: 0.5,
+                      backoff_factor: 2,
+                      retry_statuses: [429, 500, 502, 503, 504],
+                      retry_if: ->(env, _exception) { env.status == 429 }
+    end
+
+    # Executes the HTTP request and handles errors
+    def request(method, path, params = {})
+      response = connection.public_send(method, path, params)
+      handle_response(response)
+    rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
+      raise ConnectionError, "Connection failed: #{e.message}"
+    end
+
+    # Processes the HTTP response
+    def handle_response(response)
+      return parse_json(response.body) if response.status.between?(200, 299)
+
+      handle_error_response(response)
+    end
+
+    # Handles error responses based on status code
+    def handle_error_response(response)
+      case response.status
+      when 400 then raise_bad_request_error(response)
+      when 404 then raise_not_found_error(response)
+      when 405 then raise_method_not_allowed_error(response)
+      when 429 then raise_rate_limit_error(response)
+      when 500..599 then raise_server_error(response)
+      else raise_unexpected_error(response)
+      end
+    end
+
+    # Raises a BadRequestError
+    def raise_bad_request_error(response)
+      raise BadRequestError.new('Bad request', response: response, status: 400)
+    end
+
+    # Raises a NotFoundError
+    def raise_not_found_error(response)
+      raise NotFoundError.new('Resource not found', response: response, status: 404)
+    end
+
+    # Raises a MethodNotAllowedError
+    def raise_method_not_allowed_error(response)
+      raise MethodNotAllowedError.new('Method not allowed', response: response, status: 405)
+    end
+
+    # Raises a RateLimitError with retry information
+    def raise_rate_limit_error(response)
+      retry_after = response.headers['Retry-After']&.to_i
+      raise RateLimitError.new(
+        "Rate limit exceeded. Retry after #{retry_after || 'unknown'} seconds",
+        response: response,
+        status: 429,
+        retry_after: retry_after
+      )
+    end
+
+    # Raises a ServerError
+    def raise_server_error(response)
+      raise ServerError.new("Server error (#{response.status})", response: response, status: response.status)
+    end
+
+    # Raises a generic Error for unexpected status codes
+    def raise_unexpected_error(response)
+      raise Error.new("Unexpected response (#{response.status})", response: response, status: response.status)
+    end
+
+    # Parses the JSON response
+    def parse_json(body)
+      return {} if body.nil? || body.empty?
+
+      parsed = JSON.parse(body)
+      Jikanrb::IndifferentHash.new(parsed)
+    rescue JSON::ParserError => e
+      raise ParseError, "Failed to parse JSON: #{e.message}"
+    end
+  end
+end

data/lib/jikanrb/configuration.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Jikanrb
+  # Configuration class for Jikanrb client.
+  # Allows customization of timeouts, retries, and other HTTP client settings.
+  #
+  # @example
+  #   config = Jikanrb::Configuration.new
+  #   config.read_timeout = 15
+  #   config.max_retries = 5
+  class Configuration
+    # Base URL for Jikan v4 API
+    DEFAULT_BASE_URL = 'https://api.jikan.moe/v4'
+
+    # Default timeouts (in seconds)
+    DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_READ_TIMEOUT = 10
+
+    # Rate limit: Jikan allows 60 requests/minute
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_RETRY_INTERVAL = 1
+
+    attr_accessor :base_url,
+                  :open_timeout,
+                  :read_timeout,
+                  :max_retries,
+                  :retry_interval,
+                  :user_agent,
+                  :logger
+
+    def initialize
+      @base_url = DEFAULT_BASE_URL
+      @open_timeout = DEFAULT_OPEN_TIMEOUT
+      @read_timeout = DEFAULT_READ_TIMEOUT
+      @max_retries = DEFAULT_MAX_RETRIES
+      @retry_interval = DEFAULT_RETRY_INTERVAL
+      @user_agent = "Jikanrb Ruby Gem/#{Jikanrb::VERSION}"
+      @logger = nil
+    end
+  end
+end

data/lib/jikanrb/errors.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Jikanrb
+  # Base error for the gem
+  class Error < StandardError
+    attr_reader :response, :status
+
+    def initialize(message = nil, response: nil, status: nil)
+      @response = response
+      @status = status
+      super(message)
+    end
+  end
+
+  # Configuration error
+  class ConfigurationError < Error; end
+
+  # Specific HTTP errors
+  class ClientError < Error; end
+
+  # 400 - Bad Request
+  class BadRequestError < ClientError; end
+
+  # 404 - Not Found
+  class NotFoundError < ClientError; end
+
+  # 405 - Method Not Allowed
+  class MethodNotAllowedError < ClientError; end
+
+  # 429 - Rate Limit Exceeded
+  class RateLimitError < ClientError
+    attr_reader :retry_after
+
+    def initialize(message = nil, response: nil, status: nil, retry_after: nil)
+      @retry_after = retry_after
+      super(message, response: response, status: status)
+    end
+  end
+
+  # 5xx - Server errors
+  class ServerError < Error; end
+
+  # Connection error (timeout, network issues)
+  class ConnectionError < Error; end
+
+  # Error parsing JSON
+  class ParseError < Error; end
+end

data/lib/jikanrb/pagination.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Jikanrb
+  # Pagination helper module for paginated API responses
+  #
+  # @example Iterating through all pages
+  #   client = Jikanrb::Client.new
+  #   all_anime = client.paginate(:top_anime, type: 'tv')
+  #   all_anime.each do |anime|
+  #     puts anime['title']
+  #   end
+  #
+  # @example Manual pagination
+  #   result = client.top_anime(page: 1)
+  #   pagination = Jikanrb::PaginationInfo.new(result)
+  #   puts "Page #{pagination.current_page} of #{pagination.total_pages}"
+  #   puts "Has next? #{pagination.has_next_page?}"
+  module Pagination
+    # Represents pagination information from an API response
+    class PaginationInfo
+      attr_reader :current_page, :last_visible_page, :has_next_page, :items
+
+      # @param response [Hash] API response with pagination data
+      def initialize(response)
+        @pagination = response['pagination'] || {}
+        @current_page = @pagination['current_page'] || 1
+        @last_visible_page = @pagination['last_visible_page'] || 1
+        @has_next_page = @pagination['has_next_page'] || false
+        @items = @pagination['items'] || {}
+      end
+
+      # Check if there's a next page
+      # @return [Boolean]
+      def has_next_page?
+        @has_next_page
+      end
+
+      # Check if there's a previous page
+      # @return [Boolean]
+      def has_previous_page?
+        @current_page > 1
+      end
+
+      # Get next page number
+      # @return [Integer, nil] Next page number or nil if no next page
+      def next_page
+        has_next_page? ? @current_page + 1 : nil
+      end
+
+      # Get previous page number
+      # @return [Integer, nil] Previous page number or nil if no previous page
+      def previous_page
+        has_previous_page? ? @current_page - 1 : nil
+      end
+
+      # Get total number of pages
+      # @return [Integer]
+      def total_pages
+        @last_visible_page
+      end
+
+      # Get number of items per page
+      # @return [Integer]
+      def per_page
+        @items['per_page'] || 25
+      end
+
+      # Get total number of items
+      # @return [Integer]
+      def total_items
+        @items['total'] || 0
+      end
+
+      # Get current item count
+      # @return [Integer]
+      def current_item_count
+        @items['count'] || 0
+      end
+    end
+
+    # Paginator class for iterating through all pages
+    class Paginator
+      include Enumerable
+
+      # @param client [Jikanrb::Client] Client instance
+      # @param method [Symbol] Method name to call (e.g., :top_anime)
+      # @param params [Hash] Additional parameters for the method
+      def initialize(client, method, **params)
+        @client = client
+        @method = method
+        @params = params
+        @current_page = params[:page] || 1
+      end
+
+      # Iterate through all items across all pages
+      # @yield [Hash] Each item from the API response
+      def each(&block)
+        loop do
+          response = @client.public_send(@method, **@params, page: @current_page)
+          data = response['data'] || []
+
+          data.each(&block)
+
+          pagination = PaginationInfo.new(response)
+          break unless pagination.has_next_page?
+
+          @current_page = pagination.next_page
+        end
+      end
+
+      # Get all items from all pages as an array
+      # @return [Array<Hash>] All items
+      def all
+        to_a
+      end
+
+      # Get items from the first N pages
+      # @param page_count [Integer] Number of pages to fetch
+      # @return [Array<Hash>] Items from the specified number of pages
+      def take_pages(page_count)
+        items = []
+        page_count.times do
+          response = @client.public_send(@method, **@params, page: @current_page)
+          data = response['data'] || []
+
+          items.concat(data)
+
+          pagination = PaginationInfo.new(response)
+          break unless pagination.has_next_page?
+
+          @current_page = pagination.next_page
+        end
+        items
+      end
+    end
+  end
+end

data/lib/jikanrb/utils.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Jikanrb
+  # A Hash that allows access with both Symbol and String keys.
+  # This class provides a recursive mechanism to ensure nested Hashes
+  # also behave indifferently, similar to ActiveSupport's HashWithIndifferentAccess.
+  class IndifferentHash < Hash
+    # Initializes a new IndifferentHash.
+    #
+    # @param hash [Hash] The initial hash to populate the IndifferentHash with.
+    def initialize(hash = {})
+      super()
+      hash.each { |key, value| self[key] = value }
+    end
+
+    # Retrieves the value object corresponding to the key object.
+    # The key is automatically converted to a string.
+    #
+    # @param key [Symbol, String] The key to look up.
+    # @return [Object] The value associated with the key.
+    def [](key)
+      super(convert_key(key))
+    end
+
+    # Associates the value given by value with the key given by key.
+    # The key is automatically converted to a string.
+    # The value is processed to ensure nested structures are also indifferent.
+    #
+    # @param key [Symbol, String] The key to store.
+    # @param value [Object] The value to store.
+    # @return [Object] The stored value.
+    def []=(key, value)
+      super(convert_key(key), convert_value(value))
+    end
+
+    # Returns a key's value, or the default value if the key is not found.
+    # The key is automatically converted to a string.
+    #
+    # @param key [Symbol, String] The key to look up.
+    # @param args [Array] Optional default value or block.
+    # @return [Object] The value associated with the key.
+    def fetch(key, *args)
+      super(convert_key(key), *args)
+    end
+
+    # Returns true if the given key is present in the hash.
+    # The key is automatically converted to a string.
+    #
+    # @param key [Symbol, String] The key to check.
+    # @return [Boolean] True if the key exists, false otherwise.
+    def key?(key)
+      super(convert_key(key))
+    end
+
+    alias include? key?
+    alias has_key? key?
+    alias member? key?
+
+    protected
+
+    # Converts the key to a String if it is a Symbol.
+    #
+    # @param key [Object] The key to convert.
+    # @return [String, Object] The converted key.
+    def convert_key(key)
+      key.is_a?(Symbol) ? key.to_s : key
+    end
+
+    # Recursively converts Hash values to IndifferentHash.
+    # Also handles Arrays of Hashes.
+    #
+    # @param value [Object] The value to convert.
+    # @return [Object] The converted value.
+    def convert_value(value)
+      case value
+      when Hash
+        IndifferentHash.new(value)
+      when Array
+        value.map { |v| convert_value(v) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/jikanrb/version.rb

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

data/lib/jikanrb.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require_relative 'jikanrb/version'
+require_relative 'jikanrb/configuration'
+require_relative 'jikanrb/errors'
+require_relative 'jikanrb/pagination'
+require_relative 'jikanrb/client'
+require_relative 'jikanrb/utils'
+
+# Jikanrb is a modern Ruby wrapper for the Jikan REST API v4.
+# Provides easy access to anime, manga, characters, and more from MyAnimeList.
+#
+# @example Basic usage
+#   client = Jikanrb::Client.new
+#   anime = client.anime(1) # Cowboy Bebop
+#
+# @example Using global configuration
+#   Jikanrb.configure do |config|
+#     config.read_timeout = 15
+#   end
+#   anime = Jikanrb.anime(1)
+module Jikanrb
+  class << self
+    attr_writer :configuration
+
+    # Global configuration for the gem
+    #
+    # @return [Configuration] Current configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configures the gem with a block
+    #
+    # @example
+    #   Jikanrb.configure do |config|
+    #     config.read_timeout = 15
+    #     config.logger = Logger.new($stdout)
+    #   end
+    #
+    # @yield [config] Configuration block
+    # @yieldparam config [Configuration] Configuration object
+    def configure
+      yield(configuration)
+    end
+
+    # Resets configuration to default values
+    #
+    # @return [Configuration] New configuration
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Default client using global configuration
+    #
+    # @return [Client] Configured client
+    def client
+      @client ||= Client.new { |config| configure_client(config) }
+    end
+
+    # Resets the client (useful after changing configuration)
+    #
+    # @return [nil]
+    def reset_client!
+      @client = nil
+    end
+
+    # Convenience methods that delegate to the default client
+    # Allows using Jikanrb.anime(1) directly
+
+    # @see Client#anime
+    def anime(id, full: false)
+      client.anime(id, full: full)
+    end
+
+    # @see Client#manga
+    def manga(id, full: false)
+      client.manga(id, full: full)
+    end
+
+    # @see Client#character
+    def character(id, full: false)
+      client.character(id, full: full)
+    end
+
+    # @see Client#person
+    def person(id, full: false)
+      client.person(id, full: full)
+    end
+
+    # @see Client#search_anime
+    def search_anime(query, **params)
+      client.search_anime(query, **params)
+    end
+
+    # @see Client#search_manga
+    def search_manga(query, **params)
+      client.search_manga(query, **params)
+    end
+
+    # @see Client#top_anime
+    def top_anime(type: nil, filter: nil, page: 1)
+      client.top_anime(type: type, filter: filter, page: page)
+    end
+
+    # @see Client#top_manga
+    def top_manga(type: nil, filter: nil, page: 1)
+      client.top_manga(type: type, filter: filter, page: page)
+    end
+
+    # @see Client#season
+    def season(year, season, page: 1)
+      client.season(year, season, page: page)
+    end
+
+    # @see Client#season_now
+    def season_now(page: 1)
+      client.season_now(page: page)
+    end
+
+    # @see Client#schedules
+    def schedules(day: nil)
+      client.schedules(day: day)
+    end
+
+    private
+
+    # Configures a client instance with global configuration settings
+    #
+    # @param config [Configuration] Client configuration object
+    # @return [void]
+    # rubocop:disable Metrics/AbcSize
+    def configure_client(config)
+      config.base_url = configuration.base_url
+      config.open_timeout = configuration.open_timeout
+      config.read_timeout = configuration.read_timeout
+      config.max_retries = configuration.max_retries
+      config.retry_interval = configuration.retry_interval
+      config.user_agent = configuration.user_agent
+      config.logger = configuration.logger
+    end
+    # rubocop:enable Metrics/AbcSize
+  end
+end

data/sig/jikanrb.rbs

@@ -0,0 +1,4 @@
+module Jikanrb
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: jikanrb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sergio Brocos
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-01-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A modern, well-documented Ruby wrapper for the Jikan REST API v4. Provides
+  easy access to anime, manga, characters, and more from MyAnimeList.
+email:
+- sergiobrocos@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".claude/settings.local.json"
+- ".ruby-version"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/jikanrb.rb
+- lib/jikanrb/client.rb
+- lib/jikanrb/configuration.rb
+- lib/jikanrb/errors.rb
+- lib/jikanrb/pagination.rb
+- lib/jikanrb/utils.rb
+- lib/jikanrb/version.rb
+- sig/jikanrb.rbs
+homepage: https://github.com/tuusuario/jikanrb
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/tuusuario/jikanrb
+  source_code_uri: https://github.com/tuusuario/jikanrb
+  changelog_uri: https://github.com/tuusuario/jikanrb/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/jikanrb
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key:
+specification_version: 4
+summary: Ruby client for Jikan API v4 (Unofficial MyAnimeList API)
+test_files: []