shikimori-api 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 47e86dd12c49f262d518820a7c3572c8de8a73a2d7047891819a2c6be46daf83
+  data.tar.gz: 1b2872e10096765da94493d387061870757a041405fbd54a4baf76e5da19c04b
+SHA512:
+  metadata.gz: acfec6a1d8fdf30813debd7fe2dbf423f4c531a48e2c57c8ee43b7b243e69824de8c7a30aa40e1ec64bb48d94497725077ac84811a27f3f1d6f28cad4b589cc3
+  data.tar.gz: d253b3dc0191aec63c8aaca69ea258c9f63cdaf5d2cc31f140d628acfbec18abf1bf65dcfb5bccccd2025373fe8f867a8723b05ee4399d0a02353fd1611b34a6

data/README.md

@@ -0,0 +1,20 @@
+[![CI](https://github.com/iwdt/shikikit/actions/workflows/main.yml/badge.svg)](https://github.com/iwdt/shikikit/actions/workflows/main.yml) [![codecov](https://codecov.io/gh/iwdt/shikikit/graph/badge.svg)](https://codecov.io/gh/iwdt/shikikit)
+
+# Shikikit
+Ruby toolkit for the [Shikimori API](https://shikimori.one)
+
+## TODO:
+- logger
+- #as_app
+- proxy config
+- oauth methods on API
+- optional auto refresh token
+- more information at errors
+- more tests
+- entities for responses
+- contracts for requests (client-side validations)
+- better documentation
+- mutator
+- CI/CD
+- auto version increment on main branch pushing
+- deploy to rubygems

data/lib/shikimori/api/client.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'rest'
+require_relative 'uri'
+require_relative 'v1'
+require_relative 'v2'
+
+module Shikimori
+  module API
+    # Client to call shikimoris API
+    class Client
+      # @return [String] Default site url
+      DEFAULT_SITE_URL = 'https://shikimori.one/'
+
+      attr_reader :v1, :v2
+
+      def initialize(site = DEFAULT_SITE_URL, app_name:, access_token:, refresh_token:)
+        rest = REST.new(
+          access_token: access_token,
+          refresh_token: refresh_token,
+          app_name: app_name
+        )
+        @v1 = V1.new(
+          base_url: URI.new(site).join('api/'),
+          rest: rest
+        )
+        @v2 = V2.new(
+          base_url: URI.new(site).join('api/v2/'),
+          rest: rest
+        )
+      end
+    end
+  end
+end

data/lib/shikimori/api/errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Shikimori
+  module API
+    class RequestError < StandardError; end
+
+    class NotFoundError < RequestError; end
+    class ForbiddenError < RequestError; end
+
+    # Error, when request is bad
+    class BadRequestError < RequestError
+      attr_reader :errors
+
+      def initialize(errors)
+        @errors = errors.is_a?(Hash) ? errors['errors'] : errors
+
+        super("Bad request. Errors:\n\t#{@errors.join("\n\t")}")
+      end
+    end
+  end
+end

data/lib/shikimori/api/rest.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Shikimori
+  module API
+    # Helpers to make requests
+    class REST
+      def initialize(app_name:, access_token:, refresh_token:)
+        @app_name = app_name
+        @access_token = access_token
+        @refresh_token = refresh_token
+      end
+
+      def get(uri, **options)
+        _response, json = request(:get, uri, **options)
+        json
+      end
+
+      def post(uri, data, **options)
+        _response, json = request(:post, uri, data, **options)
+        json
+      end
+
+      def put(uri, data, **options)
+        _response, json = request(:put, uri, data, **options)
+        json
+      end
+
+      def delete(uri, **options)
+        response, _json = request(:delete, uri, **options)
+        [Net::HTTPNoContent, Net::HTTPSuccess].any? { response.is_a?(_1) }
+      end
+
+      private
+
+      def request(method, uri, body = nil, **options)
+        request = build_request(method, uri, **options)
+        response = start_request(uri, request, body, **options)
+
+        [response, parse_response(response)]
+      end
+
+      def build_request(method, uri, **options)
+        headers = headers_from(options)
+        query = query_params_from(uri, options)
+        uri.query = query if !query.nil? && !query.empty?
+
+        case method
+        when :get
+          Net::HTTP::Get.new(uri, headers)
+        when :post
+          Net::HTTP::Post.new(uri, headers)
+        when :put
+          Net::HTTP::Put.new(uri, headers)
+        when :delete
+          Net::HTTP::Delete.new(uri, headers)
+        end
+      end
+
+      def start_request(uri, request, body = nil, **options)
+        unless body.nil?
+          if options.fetch(:as_form, false)
+            request.set_form(body, 'multipart/form-data')
+          else
+            request.body = body.to_json
+          end
+        end
+
+        Net::HTTP.start(
+          uri.hostname.to_s, uri.port,
+          :ENV, nil, nil, nil,
+          use_ssl: uri.scheme == 'https'
+        ) do |http|
+          http.request(request)
+        end
+      end
+
+      def parse_response(response)
+        case response
+        when Net::HTTPNoContent
+          {}
+        when Net::HTTPSuccess, Net::HTTPCreated
+          json_parse_response_body(response.body)
+        when Net::HTTPForbidden
+          raise ForbiddenError
+        when Net::HTTPNotFound
+          raise NotFoundError
+        when Net::HTTPUnprocessableEntity, Net::HTTPBadRequest
+          raise BadRequestError, json_parse_response_body(response.body)
+        end
+      end
+
+      def json_parse_response_body(body)
+        JSON.parse(body&.empty? ? '{}' : body)
+      rescue JSON::ParserError
+        {}
+      end
+
+      def headers_from(options)
+        (options[:headers] || {}).merge(
+          'Content-Type' => 'application/json',
+          'Authorization' => "Bearer #{@access_token}",
+          'User-Agent' => @app_name
+        )
+      end
+
+      def query_params_from(uri, options)
+        queries = ::URI.decode_www_form uri.query || ''
+        (options[:query] || {}).each do |key, value|
+          queries << [key, value]
+        end
+        ::URI.encode_www_form(queries)
+      end
+    end
+  end
+end

data/lib/shikimori/api/uri.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Shikimori
+  module API
+    # Helper to working with URI object
+    class URI
+      attr_reader :url
+
+      def initialize(uri)
+        @url = URI(uri.to_s)
+      end
+
+      def join(*path)
+        self.class.new ::URI.join(@url, path.join('/'))
+      end
+    end
+  end
+end

data/lib/shikimori/api/v1/achievements.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Shikimori
+  module API
+    class V1
+      # Methods for the Achievements API
+      #
+      # @see https://shikimori.one/api/doc/1.0/achievements Shikimori's API documentation
+      module Achievements
+        # Get list of Achievements
+        #
+        # @param user_id [Integer] User's ID
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Array<Hash>] Array of hashes representing user's achievements
+        #
+        # @see https://shikimori.one/api/doc/1.0/achievements/index Shikimori's API documentation
+        # @example Get a achievements for user with id equal to 1
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.achievements(user_id: 1) #=> [{ id: 1, ... }]
+        def achievements(user_id:, headers: nil, **query)
+          rest.get base_url.join('achievements').url, headers: headers, query: { user_id: user_id }.merge(query)
+        end
+      end
+    end
+  end
+end

data/lib/shikimori/api/v1/animes.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module Shikimori
+  module API
+    class V1
+      # Methods for the Animes API
+      #
+      # @see https://shikimori.one/api/doc/1.0/animes Shikimori's API documentation
+      module Animes
+        # Get list of anime titles
+        #
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Filters and pagination for animes
+        # @option query [Integer] :page Number of page. Must be between 1 and 100000
+        # @option query [Integer] :limit Number of titles per page. Must be a lower or equal that 50
+        # @option query ["id", "id_desc", "ranked",
+        #  "kind", "popularity", "name",
+        #  "aired_on", "episodes", "status",
+        #  "random", "ranked_random",
+        #  "ranked_shiki", "created_at", "created_at_desc"] :order Sorting type.
+        # @option query [String, Symbol] :type Type of title. Deprecated! use :kind instead
+        # @option query ["tv", "movie", "ova",
+        #   "ona", "special", "tv_special",
+        #   "music", "pv", "cm", "tv_13",
+        #   "tv_24", "tv_48"] :kind Type of anime title
+        # @option query ["anons", "ongoing", "released"] :status Anime title status
+        # @option query [String] :season Anime season. Examples: "summer_2017", "2016", "2014_2016", "199x"
+        # @option query [Integer] :score Minimal anime score
+        # @option query ["S", "D", "F"] :duration Duration of anime title episode,
+        #   where S – less than 10 minutes, D – less than 30 minutes and F – more than 30 minutes
+        # @option query ["none", "g", "pg", "pg_13", "r", "r_plus", "rx"] :rating Age limit level of anime title
+        # @option query [String] :genre List of genre ids separated by comma
+        # @option query [String] :genre_v2 List of genre v2 ids separated by comma
+        # @option query [String] :studio List of studio ids separated by comma
+        # @option query [String] :franchise List of franchises separated by comma
+        # @option query [TrueClass, FalseClass] :censored Set to false to allow hentai, yaoi and yuri
+        # @option query ["planned", "watching", "rewatching",
+        #   "completed", "on_hold", "dropped"] :mylist Status of anime in current user list
+        # @option query [String] :ids List of anime ids separated by comma
+        # @option query [String] :exclude_ids List of anime ids separated by comma
+        # @option query [String] :search Search phrase to filter animes by name
+        #
+        # @return [Array<Hash>] Array of hashes representing animes
+        #
+        # @see https://shikimori.one/api/doc/1.0/animes/index Shikimori's API documentation
+        # @example Get 20 anime titles on second page
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.animes(page: 2, limit: 20) #=> [{ id: 1, ... }, { id: 2, ... }, ...]
+        # @example Get top 50 ongoing anime titles
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.animes(limit: 50, status: 'ongoing', order: 'ranked') #=> [{ id: 1, ... }, { id: 2, ... }, ...]
+        # @example Get 10 random anime titles released in the 90s
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.animes(limit: 10, order: 'random', season: '199x') #=> [{ id: 1, ... }, { id: 2, ... }, ...]
+        def animes(headers: nil, **query)
+          rest.get base_url.join('animes').url, headers: headers, query: query
+        end
+
+        # Get an anime by id
+        #
+        # @param id [#to_s] Anime id
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Hash] Hash representing anime
+        #
+        # @see https://shikimori.one/api/doc/1.0/animes/show Shikimori's API documentation
+        # @example Get anime with id equal to 1
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.anime(1) #=> { id: 1, ... }
+        def anime(id, headers: nil, **query)
+          rest.get base_url.join('animes', id.to_s).url, headers: headers, query: query
+        end
+
+        # Get an anime roles
+        #
+        # @param id [#to_s] Anime id
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Hash] Hash representing anime roles
+        #
+        # @raise [Shikimori::API::NotFoundError] if anime not exists
+        #
+        # @see https://shikimori.one/api/doc/1.0/animes/roles Shikimori's API documentation
+        # @example Get a first anime roles
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.anime_roles(1) #=> { roles: [...], roles_russian: [...], character: {...}, person: {...} }
+        def anime_roles(id, headers: nil, **query)
+          rest.get base_url.join('animes', id.to_s, 'roles').url, headers: headers, query: query
+        end
+
+        # Get an anime similar
+        #
+        # @param id [#to_s] Anime id
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Array<Hash>] Array of hashes representing similar animes
+        #
+        # @raise [Shikimori::API::NotFoundError] if anime not exists
+        #
+        # @see https://shikimori.one/api/doc/1.0/animes/similar Shikimori's API documentation
+        # @example Get a similar anime titles for anime with id equal to 1
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.anime_similar(1) #=> { id: 2, ... }
+        def anime_similar(id, headers: nil, **query)
+          rest.get base_url.join('animes', id.to_s, 'similar').url, headers: headers, query: query
+        end
+
+        # Get an related animes
+        #
+        # @param id [#to_s] Anime id
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Array<Hash>] Array of hashes representing related animes
+        #
+        # @raise [Shikimori::API::NotFoundError] if anime not exists
+        #
+        # @see https://shikimori.one/api/doc/1.0/animes/related Shikimori's API documentation
+        # @example Get a related anime, manga and ranobe titles for anime with id equal to 1
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.anime_related(1)
+        #   #=> [{ relation: "...", relation_russian: "...", anime: { id: 3, ... }, manga: { id: 1, ... } }]
+        def anime_related(id, headers: nil, **query)
+          rest.get base_url.join('animes', id.to_s, 'related').url, headers: headers, query: query
+        end
+
+        # Get an anime screenshots
+        #
+        # @param id [#to_s] Anime id
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Array<Hash>] Array of hashes representing anime screenshots
+        #
+        # @raise [Shikimori::API::NotFoundError] if anime not exists
+        #
+        # @see https://shikimori.one/api/doc/1.0/animes/screenshots Shikimori's API documentation
+        # @example Get screenshots for anime with id equal to 1
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.anime_screenshots(1) #=> [{ original: "...", preview: "..." }]
+        def anime_screenshots(id, headers: nil, **query)
+          rest.get base_url.join('animes', id.to_s, 'screenshots').url, headers: headers, query: query
+        end
+
+        # Get an anime franchise
+        #
+        # @param id [#to_s] Anime id
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Hash] Hash representing of anime's franchise tree
+        #
+        # @raise [Shikimori::API::NotFoundError] if anime not exists
+        #
+        # @see https://shikimori.one/api/doc/1.0/animes/franchise Shikimori's API documentation
+        # @example Get anime franchise tree for anime with id equal to 1
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.anime_franchise(1) #=> { links: [{ id: 1, ... }], nodes: [{ id: 1, ... }], current_id: 1 }
+        def anime_franchise(id, headers: nil, **query)
+          rest.get base_url.join('animes', id.to_s, 'franchise').url, headers: headers, query: query
+        end
+
+        # Get an anime external links
+        #
+        # @param id [#to_s] Anime id
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Array<Hash>] Array of hashes representing anime's extenal links
+        #
+        # @raise [Shikimori::API::NotFoundError] if anime not exists
+        #
+        # @see https://shikimori.one/api/doc/1.0/animes/external_links Shikimori's API documentation
+        # @example Get related external links for anime with id equal 1
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.anime_external_links(1) #=> [{ id: 1, ... }, { id: nil, ... }]
+        def anime_external_links(id, headers: nil, **query)
+          rest.get base_url.join('animes', id.to_s, 'external_links').url, headers: headers, query: query
+        end
+
+        # Get an anime topics
+        #
+        # @param id [#to_s] Anime id
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        # @option query [Integer] :page Number of page. Must be between 1 and 100000
+        # @option query [Integer] :limit Number of titles per page. Must be a lower or equal that 50
+        # @option query ['anons', 'ongoing', 'released', 'episode'] :kind Type of topic
+        # @option query [Integer] :episode Number of anime's episode. Required for :kind equal to 'episode'
+        #
+        # @return [Array<Hash>] Array of hashes representing anime's topics
+        #
+        # @raise [Shikimori::API::NotFoundError] if anime not exists
+        #
+        # @see https://shikimori.one/api/doc/1.0/animes/topics Shikimori's API documentation
+        # @example Get topics for anime with id equal 1
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.anime_topics(1) #=> [{ id: 1, ... }]
+        def anime_topics(id, headers: nil, **query)
+          rest.get base_url.join('animes', id.to_s, 'topics').url, headers: headers, query: query
+        end
+      end
+    end
+  end
+end

data/lib/shikimori/api/v1/appear.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Shikimori
+  module API
+    class V1
+      # Methods for the Appears API
+      #
+      # @see https://shikimori.one/api/doc/1.0/appear Shikimori's API documentation
+      module Appear
+        # Mark comments or topics as read
+        #
+        # @param comment_ids [Array<#to_s>] Comment ids
+        # @param topic_ids [Array<#to_s>] Topic ids
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Boolean] True if mark comments or topics as read successful, false otherwise.
+        #
+        # @see https://shikimori.one/api/doc/1.0/appear/create Shikimori's API documentation
+        # @example Mark comment 7, 8 and topic 270101 as read
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.create_appear(ids: ["comment-7", "comment-8","topic-270101"]) #=> true
+        def create_appear(comment_ids: [], topic_ids: [], headers: nil, **query)
+          comments = comment_ids.map { "comment-#{_1}" }
+          topics = topic_ids.map { "topic-#{_1}" }
+
+          ids = comments + topics
+
+          rest.post base_url.join('appear').url, { ids: ids.join(',') }, headers: headers, query: query
+
+          true
+        end
+      end
+    end
+  end
+end

data/lib/shikimori/api/v1/bans.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Shikimori
+  module API
+    class V1
+      # Methods for the Bans API
+      #
+      # @see https://shikimori.one/api/doc/1.0/bans Shikimori's API documentation
+      module Bans
+        # Get list of bans
+        #
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Array<Hash>] Array of hashes representing bans
+        #
+        # @see https://shikimori.one/api/doc/1.0/bans/index Shikimori's API documentation
+        # @example Get list of bans
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.bans #=> [{ id: 1, ... }, { id: 2, ... }]
+        def bans(headers: nil, **query)
+          rest.get base_url.join('bans').url, headers: headers, query: query
+        end
+      end
+    end
+  end
+end

data/lib/shikimori/api/v1/calendars.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Shikimori
+  module API
+    class V1
+      # Methods for the Calendars API
+      #
+      # @see https://shikimori.one/api/doc/1.0/calendars Shikimori's API documentation
+      module Calendars
+        # Get a calendar
+        #
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        # @option query [TrueClass, FalseClass] :censored Set to false to allow hentai, yaoi and yuri
+        #
+        # @return [Array<Hash>] Array of hashes representing calendars
+        #
+        # @see https://shikimori.one/api/doc/1.0/calendars/show Shikimori's API documentation
+        # @example Get a calendar
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.calendar #=> [{ next_episode: 1, anime: [{ id: 1, ... }], ... }]
+        def calendar(headers: nil, **query)
+          rest.get base_url.join('calendar').url, headers: headers, query: query
+        end
+      end
+    end
+  end
+end

data/lib/shikimori/api/v1/characters.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Shikimori
+  module API
+    class V1
+      # Methods for the Characters API
+      #
+      # @see https://shikimori.one/api/doc/1.0/characters Shikimori's API documentation
+      module Characters
+        # Get list of Characters
+        #
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        # @option query [String] :search A character name for searching
+        #
+        # @return [Array<Hash>] Array of hashes representing characters
+        #
+        # @see https://shikimori.one/api/doc/1.0/characters/search Shikimori's API documentation
+        # @example Search characters
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.characters(search: 'asdf') #=> [{ id: 1, ... }]
+        def characters(headers: nil, **query)
+          rest.get base_url.join('characters', 'search').url, headers: headers, query: query
+        end
+
+        # Get a character by id
+        #
+        # @param id [#to_s] Character id
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Hash] Hash representing character
+        #
+        # @see https://shikimori.one/api/doc/1.0/characters/show Shikimori's API documentation
+        # @example Get character with id equal to 1
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.character(1) #=> { id: 1, ... }
+        def character(id, headers: nil, **query)
+          rest.get base_url.join('characters', id.to_s).url, headers: headers, query: query
+        end
+      end
+    end
+  end
+end