shikimori-api 1.0.0

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

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Shikimori
+  module API
+    class V1
+      # Methods for the Favorites API
+      #
+      # @see https://shikimori.one/api/doc/1.0/favorites Shikimori's API documentation
+      module Favorites
+        # Add object to favorites
+        #
+        # @param id [#to_s] Favorite's object id
+        # @param type ['person', 'anime', 'manga', 'ranobe', 'character'] Favorite's object type
+        # @param person_type ['common', 'seyu', 'mangaka', 'producer', 'person'] Person type.
+        #   Required for :type equal to person
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Bool] True if create a new favorite is successful
+        #
+        # @see https://shikimori.one/api/doc/1.0/favorites/create Shikimori's API documentation
+        # @example Add mangaka with id equal to 1 to favorites
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.create_favorite(1, type: 'person', person_type: 'mangaka')
+        # @example Add anime with id equal to 1 to favorites
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.create_favorite(1, type: 'anime') #=> { success: true, notice: '...' }
+        def create_favorite(id, type:, person_type: 'person', headers: nil, **query)
+          path = creation_favorite_path_by(type.to_s.downcase, id.to_s, person_type)
+          rest.post base_url.join('favorites', *path).url, {}, headers: headers, query: query
+
+          true
+        end
+
+        # Delete Favorite
+        #
+        # @param id [String, Integer] Favorite id
+        # @param type ['person', 'anime', 'manga', 'ranobe', 'character'] Favorite's object type
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Boolean] True if deletion successful, false otherwise.
+        #
+        # @see https://shikimori.one/api/doc/1.0/favorites/destroy Shikimori's API documentation
+        # @example Delete person with id equal to 1 from favorites
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.delete_favorite(1, type: 'person')
+        # @example Delete anime with id equal to 1 from favorites
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.delete_favorite(1, type: 'anime') #=> true
+        def delete_favorite(id, type:, headers: nil, **query)
+          path = deletion_favorite_path_by(type.to_s.downcase, id.to_s)
+          rest.delete base_url.join('favorites', *path).url, headers: headers, query: query
+
+          true
+        end
+
+        # Reorder favorite
+        #
+        # @param id [#to_s] Favorite's id
+        # @param position [Integer] New position for favroite. Must be greater or equal than 0
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Bool] True if reordering is successful
+        #
+        # @see https://shikimori.one/api/doc/1.0/favorites/reorder Shikimori's API documentation
+        # @example Reorder favorite with id equal to 1 to 10 position
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.reorder_favorite(1, position: 10)
+        def reorder_favorite(id, position:, headers: nil, **query)
+          rest.post(
+            base_url.join('favorites', id.to_s, 'reorder').url,
+            { new_index: position },
+            headers: headers, query: query
+          )
+
+          true
+        end
+
+        private
+
+        # Generate path for adding to favorites
+        #
+        # @param type [String] Type of favorite
+        # @param id [String] Favorite's object id
+        # @param person_type [String] Person type
+        #
+        # @return [Array<String>] Array of path to adding object to favorites
+        def creation_favorite_path_by(type, id, person_type = 'person')
+          case type
+          when 'person'
+            ['Person', id, person_type]
+          when 'manga'
+            ['Manga', id]
+          when 'ranobe'
+            ['Ranobe', id]
+          when 'character'
+            ['Character', id]
+          else
+            ['Anime', id]
+          end
+        end
+
+        # Generate path for deletion from favorites
+        #
+        # @param type [String] Type of favorite
+        # @param id [String] Favorite's object id
+        #
+        # @return [Array<String>] Array of path to delete object from favorites
+        def deletion_favorite_path_by(type, id)
+          case type
+          when 'person'
+            ['Person', id]
+          when 'manga'
+            ['Manga', id]
+          when 'ranobe'
+            ['Ranobe', id]
+          when 'character'
+            ['Character', id]
+          else
+            ['Anime', id]
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Shikimori
+  module API
+    class V1
+      # Methods for the Friends API
+      #
+      # @see https://shikimori.one/api/doc/1.0/friends Shikimori's API documentation
+      module Friends
+        # Create friend by user_id.
+        # Requires `friends` oauth scope
+        #
+        # @param user_id [#to_s] User id that add to friends
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Boolean] True if added to friends
+        #
+        # @see https://shikimori.one/api/doc/1.0/friends/create Shikimori's API documentation
+        # @example Add to friends a user with id equal to 1
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.create_friend(1)
+        def create_friend(user_id, headers: nil, **query)
+          rest.post base_url.join('friends', user_id.to_s).url, {}, headers: headers, query: query
+
+          true
+        end
+
+        # Delete friend by user id.
+        # Requires `friends` oauth scope
+        #
+        # @param user_id [#to_s] Friend id
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Boolean] True if deletion successful, false otherwise.
+        #
+        # @see https://shikimori.one/api/doc/1.0/friends/destroy Shikimori's API documentation
+        # @example Delete a user from friends by id equal to 1
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #
+        #   client.v1.delete_friend(1)
+        def delete_friend(user_id, headers: nil, **query)
+          rest.delete base_url.join('friends', user_id.to_s).url, headers: headers, query: query
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Shikimori
+  module API
+    class V1
+      # Methods for the Ignores API
+      #
+      # @deprecated Use {Shikimori::API::V2::UserIgnore} instead
+      #
+      # @see https://shikimori.one/api/doc/1.0/ignores Shikimori's API documentation
+      module Ignores
+        # Add user to ignore by user id.
+        # Requires `ignores` oauth scope
+        #
+        # @param user_id [#to_s] User id that add to ignores
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Hash] Hash representing created user ignore
+        #
+        # @see https://shikimori.one/api/doc/1.0/ignores/create Shikimori's API documentation
+        # @example Add to ignore a user with id equal to 1
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.create_ignore(1)
+        #
+        # @deprecated Use {Shikimori::API::V2::UserIgnore#create_user_ignore} instead
+        def create_ignore(user_id, headers: nil, **query)
+          rest.post base_url.join('ignores', user_id.to_s).url, {}, headers: headers, query: query
+
+          true
+        end
+
+        # Delete a user from ignores by user id.
+        # Requires `ignores` oauth scope
+        #
+        # @param user_id [#to_s] User id that remove from ignores
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Boolean] True if deletion successful, false otherwise.
+        #
+        # @see https://shikimori.one/api/doc/1.0/ignores/destroy Shikimori's API documentation
+        # @example Delete a ignore
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.delete_ignore(1)
+        #
+        # @deprecated Use {Shikimori::API::V2::UserIgnore#delete_user_ignore} instead
+        def delete_ignore(user_id, headers: nil, **query)
+          rest.delete base_url.join('ignores', user_id.to_s).url, headers: headers, query: query
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module Shikimori
+  module API
+    class V1
+      # Methods for the Mangas API
+      #
+      # @see https://shikimori.one/api/doc/1.0/mangas Shikimori's API documentation
+      module Mangas
+        # Get list of manga titles
+        #
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Filters and pagination for mangas
+        # @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", "chapters",
+        #  "kind", "popularity", "name",
+        #  "aired_on", "volumes", "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 ["manga", "manhwa", "manhua",
+        #   "light_novel", "novel",
+        #   "one_shot", "doujin"] :kind Type of manga title
+        # @option query ["anons", "ongoing", "released", "paused", "discontinued"] :status Manga title status
+        # @option query [String] :season Manga season. Examples: "summer_2017", "2016", "2014_2016", "199x"
+        # @option query [Integer] :score Minimal manga score
+        # @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] :publisher List of publisher 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 mangas by name
+        #
+        # @return [Array<Hash>] Array of hashes representing mangas
+        #
+        # @see https://shikimori.one/api/doc/1.0/mangas/index Shikimori's API documentation
+        # @example Get 20 manga titles on second page
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.mangas(page: 2, limit: 20) #=> [{ id: 1, ... }, { id: 2, ... }, ...]
+        # @example Get top 50 ongoing manga titles
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.mangas(limit: 50, status: 'ongoing', order: 'ranked') #=> [{ id: 1, ... }, { id: 2, ... }, ...]
+        # @example Get 10 random manga titles released in the 90s
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.mangas(limit: 10, order: 'random', season: '199x') #=> [{ id: 1, ... }, { id: 2, ... }, ...]
+        def mangas(headers: nil, **query)
+          rest.get base_url.join('mangas').url, headers: headers, query: query
+        end
+
+        # Get an manga by id
+        #
+        # @param id [#to_s] Manga id
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Hash] Hash representing Manga
+        #
+        # @see https://shikimori.one/api/doc/1.0/mangas/show Shikimori's API documentation
+        # @example Get manga with id equal to 1
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.manga(1) #=> { id: 1, ... }
+        def manga(id, headers: nil, **query)
+          rest.get base_url.join('mangas', id.to_s).url, headers: headers, query: query
+        end
+
+        # Get an manga roles
+        #
+        # @param id [#to_s] manga id
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Hash] Hash representing manga roles
+        #
+        # @see https://shikimori.one/api/doc/1.0/mangas/roles Shikimori's API documentation
+        # @example Get a first manga roles
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.manga_roles(1) #=> { roles: [...], roles_russian: [...], character: {...}, person: {...} }
+        def manga_roles(id, headers: nil, **query)
+          rest.get base_url.join('mangas', id.to_s, 'roles').url, headers: headers, query: query
+        end
+
+        # Get an manga similar
+        #
+        # @param id [#to_s] Manga id
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Array<Hash>] Array of hashes representing similar mangas
+        #
+        # @see https://shikimori.one/api/doc/1.0/mangas/similar Shikimori's API documentation
+        # @example Get a similar manga titles for manga with id equal to 1
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.manga_similar(1) #=> { id: 2, ... }
+        def manga_similar(id, headers: nil, **query)
+          rest.get base_url.join('mangas', id.to_s, 'similar').url, headers: headers, query: query
+        end
+
+        # Get an related mangas
+        #
+        # @param id [#to_s] Manga id
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Array<Hash>] Array of hashes representing related mangas
+        #
+        # @see https://shikimori.one/api/doc/1.0/mangas/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.manga_related(1)
+        #   #=> [{ relation: "...", relation_russian: "...", anime: { id: 3, ... }, manga: { id: 1, ... } }]
+        def manga_related(id, headers: nil, **query)
+          rest.get base_url.join('mangas', id.to_s, 'related').url, headers: headers, query: query
+        end
+
+        # Get an manga franchise
+        #
+        # @param id [#to_s] Manga id
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Hash] Hash representing of manga's franchise tree
+        #
+        # @see https://shikimori.one/api/doc/1.0/mangas/franchise Shikimori's API documentation
+        # @example Get manga franchise tree for manga with id equal to 1
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.manga_franchise(1) #=> { links: [{ id: 1, ... }], nodes: [{ id: 1, ... }], current_id: 1 }
+        def manga_franchise(id, headers: nil, **query)
+          rest.get base_url.join('mangas', id.to_s, 'franchise').url, headers: headers, query: query
+        end
+
+        # Get an manga external links
+        #
+        # @param id [#to_s] Manga id
+        # @param headers [Hash] Request headers
+        # @param query [Hash] Query string parameters for request
+        #
+        # @return [Array<Hash>] Array of hashes representing manga's extenal links
+        #
+        # @see https://shikimori.one/api/doc/1.0/mangas/external_links Shikimori's API documentation
+        # @example Get related external links for manga with id equal 1
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.manga_external_links(1) #=> [{ id: 1, ... }, { id: nil, ... }]
+        def manga_external_links(id, headers: nil, **query)
+          rest.get base_url.join('mangas', id.to_s, 'external_links').url, headers: headers, query: query
+        end
+
+        # Get an manga topics
+        #
+        # @param id [#to_s] Manga 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
+        # @return [Array<Hash>] Array of hashes representing manga's topics
+        #
+        # @see https://shikimori.one/api/doc/1.0/mangas/topics Shikimori's API documentation
+        # @example Get topics for manga with id equal 1
+        #   client = Shikimori::API::Client.new(
+        #     app_name: 'Api Test',
+        #     aceess_token: '****',
+        #     refresh_token: '****'
+        #   )
+        #   client.v1.manga_topics(1) #=> [{ id: 1, ... }]
+        def manga_topics(id, headers: nil, **query)
+          rest.get base_url.join('mangas', id.to_s, 'topics').url, headers: headers, query: query
+        end
+      end
+    end
+  end
+end