renshuu 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 182e63b036401b107a66bf329425dd16dbc35ae63dc0326996ccae79ee95484c
-  data.tar.gz: 2ffe79bf4e6a7d9e22bf15cfe698b88b441a1ef7cfc185e4ee93d0438555ff59
+  metadata.gz: df6e1af568b7bb56df71d9bd55a92b9a64e0319e4a0daa6df5afec0a4c2d905e
+  data.tar.gz: 06fe422633574facfb49f0c9fbc53b52969026fe9df4fd8f50cf7904768ab379
 SHA512:
-  metadata.gz: b480fa63633cdb81180c5703204b8867efa75903f5e9d197df99979064a2fffd5eb314ab01cece8c237dd4cd4826de58d2dd3cbd18700ff0683208b4d869250e
-  data.tar.gz: 0dbf167eb256825633f0cb9069997042e80869e3e58eacb7b42f8cfd25db7cc015e8e356f834d4b586a59239981805481ab4f8d7ec06b85c9240e3a7f83c22c4
+  metadata.gz: 73dd997e5c0ef3fcd15de076192d660ee36158f7ac8bc54a54d3ce98281358595ae5b9523a8918fd66d2e5a9ebedd04d24c345137fe54e3b2f851ae5733f6813
+  data.tar.gz: 2c639cbe92edd74939c8b9ca2785c64a68b0d827c61f50d638e26605dff70169c1354893fc2a05ff976e4d6a40e5530145889520691555d18719caf714a1050d

data/.rubocop.yml

@@ -9,6 +9,10 @@ AllCops:
   NewCops: enable
   TargetRubyVersion: 3.3
 
+Layout/CaseIndentation:
+  EnforcedStyle: end
+Layout/EndAlignment:
+  EnforcedStyleAlignWith: start_of_line
 Layout/LineLength:
   Max: 80
 Layout/MultilineMethodCallIndentation:
@@ -22,4 +26,4 @@ RSpec/NestedGroups:
   Max: 4
 RSpec/SpecFilePathFormat:
   Exclude:
-    - spec/renshuu/models/*_spec.rb
+    - spec/renshuu/models/**/*_spec.rb

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.0.0] - 2025-12-09
+
+### Added
+
+- Schedules
+- Lists
+
+## [0.2.0] - 2025-12-03
+
+### Added
+
+- Word dictionary and lookup
+- Grammar dictionary and lookup
+- Sentence dictionary and lookup
+
 ## [0.1.0] - 2025-07-31
 
 ### Added

data/README.md

@@ -2,7 +2,16 @@
 
 Ruby wrapper for [Renshuu], the Japanese learning platform.
 
+[![Pipeline status badge][pipeline]][pipelines]
+[![Coverage badge][coverage]][pipelines]
+[![Latest release badge][latest-release]][releases]
+
 [Renshuu]: https://renshuu.org
+[pipeline]: https://gitlab.com/Richard-Degenne/renshuu/badges/dev/pipeline.svg?ignore_skipped=true
+[pipelines]: https://gitlab.com/Richard-Degenne/renshuu/-/pipelines/
+[coverage]: https://gitlab.com/Richard-Degenne/renshuu/badges/dev/coverage.svg
+[latest-release]: https://gitlab.com/Richard-Degenne/renshuu/-/badges/release.svg
+[releases]: https://gitlab.com/Richard-Degenne/renshuu/-/releases/
 
 ## Installation
 
@@ -61,6 +70,120 @@ Renshuu::Kanji.search('たべる')
 Renshuu::Kanji.get('紅')
 ```
 
+### Vocabulary dictionary
+
+```ruby
+# Searches the word dictionary
+Renshuu::Word.search('to eat')
+Renshuu::Word.search('taberu')
+Renshuu::Word.search('食べる')
+
+# Retrieves a word from its identifier
+Renshuu::Word.get(370)
+```
+
+### Grammar dictionary
+
+```ruby
+# Searches the grammar dictionary
+Renshuu::Grammar.search('without')
+Renshuu::Grammar.search('ましょう')
+
+# Retrieves a specific grammar entry from its identifier
+Renshuu::Grammar.get(6)
+```
+
+### Sentence dictionary
+
+```ruby
+# Searches the sentence dictionary
+Renshuu::Sentence.search('to eat')
+Renshuu::Sentence.search('ケーキ')
+
+# Retrieves sentences for a given word.
+Renshuu::Sentence.word_search(370)
+
+# Syntactic sugar for `Renshuu::Word`.
+word = Renshuu::Word.get(370)
+word.sentences
+```
+
+### Study lists
+
+```ruby
+# Lists the user's study lists
+Renshuu::Schedule.list
+
+# Retrieves a specific list
+Renshuu::Schedule.get(36555)
+
+# Retrieves the contents of a list
+list = Renshuu::Schedule.get(36555)
+list.contents
+list.contents(page: 2, group: :review_today)
+
+# Manage list content
+kanji = Renshuu::Kanji.get('食')
+kanji.add_to_list(list)
+kanji.remove_from_list(list)
+# Or
+list.add(kanji)
+list.remove(kanji)
+
+word = Renshuu::Word.get(370)
+word.add_to_list(list)
+word.remove_from_list(list)
+# Or
+list.add(word)
+list.remove(word)
+
+grammar = Renshuu::Grammar.get(927)
+grammar.add_to_list(list)
+grammar.remove_from_list(list)
+# Or
+list.add(grammar)
+list.remove(grammar)
+```
+
+### Lists
+
+```ruby
+# Lists the user's lists
+Renshuu::List.list
+
+# Retrieves the contents of a list
+list = Renshuu::List.list.first.lists.first # Browsing the list groups
+list.contents
+list.contents(page: 2)
+
+# Manage list content
+kanji = Renshuu::Kanji.get('食')
+kanji.add_to_list(list)
+kanji.remove_from_list(list)
+# Or
+list.add(kanji)
+list.remove(kanji)
+
+word = Renshuu::Word.get(370)
+word.add_to_list(list)
+word.remove_from_list(list)
+# Or
+list.add(word)
+list.remove(word)
+
+grammar = Renshuu::Grammar.get(927)
+grammar.add_to_list(list)
+grammar.remove_from_list(list)
+# Or
+list.add(grammar)
+list.remove(grammar)
+```
+
+## Documentation
+
+A comprehensive documenation is available at
+<https://renshuu.richarddegenne.fr>.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run

data/lib/renshuu/models/grammar.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Renshuu
+  ##
+  # Model class for grammar entries.
+  class Grammar < Model
+    include Schedulable
+    include Listable
+
+    ##
+    # Searches the grammar dictionary.
+    #
+    # @param [String] value
+    #
+    # @return [Array<Grammar>]
+    def self.search(value)
+      Renshuu.client.query(:get, 'v1/grammar/search', params: { value: })
+        .fetch(:grammar).map { new(_1) }
+    end
+
+    ##
+    # Retrieves a grammar entry fom the dictionary.
+    #
+    # @param [Integer] id
+    #
+    # @return [Grammar]
+    def self.get(id)
+      Renshuu.client.query(:get, "v1/grammar/#{id}").then { new(_1) }
+    end
+
+    ##
+    # @!attribute [r] id
+    #   @return [String]
+    attribute :id, Types::String
+    ##
+    # @!attribute [r] title_english
+    #   @return [String]
+    attribute :title_english, Types::String
+    ##
+    # @!attribute [r] title_japanese
+    #   @return [String]
+    attribute :title_japanese, Types::String
+    ##
+    # @!attribute [r] meaning
+    #   @return [Hash{String => String}]
+    attribute :meaning, Types::Hash.map(Types::String, Types::String)
+    ##
+    # @!attribute [r] meaning_long
+    #   @return [Hash{String => String}]
+    attribute :meaning_long, Types::Hash.map(Types::String, Types::String)
+
+    ##
+    # Model class for grammar models.
+    class Model < Model
+      ##
+      # @!attribute [r] japanese
+      #   @return [String]
+      attribute :japanese, Types::String
+      ##
+      # @!attribute [r] hiragana
+      #   @return [String]
+      attribute :hiragana, Types::String
+      ##
+      # @!attribute [r] meanings
+      #   @return [Hash{String => String}]
+      attribute :meanings, Types::Hash.map(Types::String, Types::String)
+    end
+    ##
+    # @!attribute [r] models
+    #   @return [Array<Model>]
+    attribute(:models, Types::Array.of(Model).default { [] })
+
+    ##
+    # @!attribute [r] user_data
+    #   @return [UserData, nil]
+    attribute? :user_data, UserData
+    ##
+    # @!attribute [r] presence
+    #   @return [Presence, nil]
+    attribute? :presence, Presence
+  end
+end

data/lib/renshuu/models/kanji.rb

@@ -6,6 +6,9 @@ module Renshuu
   #
   # @see https://api.renshuu.org/docs/#/Kanji
   class Kanji < Model
+    include Schedulable
+    include Listable
+
     ##
     # Searches the Renshuu kanji dictionary.
     #
@@ -29,5 +32,82 @@ module Renshuu
       body = Renshuu.client.query(:get, "v1/kanji/#{cgi_character}")
       new(body)
     end
+
+    ##
+    # @!attribute [r] id
+    #   @return [String]
+    attribute :id, Types::String
+    ##
+    # @!attribute [r] kanji
+    #   @return [String]
+    attribute :kanji, Types::String
+    ##
+    # @!attribute [r] definition
+    #   @return [String]
+    attribute :definition, Types::String
+    ##
+    # @!attribute [r] scount
+    #   @return [Integer, nil]
+    attribute? :scount, Types::Integer
+    alias stroke_count scount
+    ##
+    # @!attribute [r] radical
+    #   @return [String, nil]
+    attribute? :radical, Types::String
+    ##
+    # @!attribute [r] radical_name
+    #   @return [String, nil]
+    attribute? :radical_name, Types::String
+    ##
+    # @!attribute [r] onyomi
+    #   @return [String, nil]
+    attribute? :onyomi, Types::String
+    ##
+    # @!attribute [r] kunyomi
+    #   @return [String, nil]
+    attribute? :kunyomi, Types::String
+    ##
+    # @!attribute [r] kanken
+    #   @return [String, nil]
+    attribute? :kanken, Types::String
+    ##
+    # @!attribute [r] jlpt
+    #   @return [String, nil]
+    attribute? :jlpt, Types::String
+
+    ##
+    # Model class for kanji's related words.
+    class RelatedWord < Model
+      ##
+      # @!attribute [r] reading
+      #   @return [String]
+      attribute :reading, Types::String
+
+      ##
+      # Model class for kanji's related words' word.
+      class Word < Model
+        ##
+        # @!attribute [r] def
+        #   @return [String]
+        attribute :def, Types::String
+        ##
+        # @!attribute [r] term
+        #   @return [String]
+        attribute :term, Types::String
+      end
+      attribute :words, Types::Array.of(Word)
+    end
+    ##
+    # @!attribute [r] rwords
+    #   @return [Array<RelatedWord>, nil]
+    attribute? :rwords, Types::Array.of(RelatedWord)
+    ##
+    # @!attribute [r] user_data
+    #   @return [UserData, nil]
+    attribute? :user_data, UserData
+    ##
+    # @!attribute [r] presence
+    #   @return [Presence, nil]
+    attribute? :presence, Presence
   end
 end

data/lib/renshuu/models/list.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Renshuu
+  ##
+  # Model class for lists.
+  #
+  # @see https://api.renshuu.org/docs/#/User
+  class List < Model
+    ##
+    # Mapping between list termtypes and model classes.
+    #
+    # @see #term_class
+    TERMTYPES = {
+      'kanji' => Kanji, 'vocab' => Word, 'grammar' => Grammar,
+      'sent' => Sentence
+    }.freeze
+
+    ##
+    # Retrives list groups from the API.
+    #
+    # @return [Array<Group>]
+    def self.list
+      body = Renshuu.client.query(:get, 'v1/lists')
+
+      body.fetch(:termtype_groups).flat_map do |termtype_group|
+        termtype = termtype_group.fetch(:termtype)
+        termtype_group.fetch(:groups).map { Group.new(termtype:, **_1) }
+      end
+    end
+
+    ##
+    # Model class for list groups, _a.k.a._ sets.
+    class Group < Model
+      ##
+      # @!attribute [r] group_title
+      #   @return [String]
+      attribute :group_title, Types::String
+      alias title group_title
+      ##
+      # @!attribute [r] termtype
+      #   @return [String]
+      attribute :termtype, Types::String
+
+      ##
+      # @!attribute [r] lists
+      #   @return [Array<List>]
+      attribute :lists, Types::Array.of(List)
+    end
+
+    ##
+    # @!attribute [r] list_id
+    #   @return [String]
+    attribute :list_id, Types::String
+    alias id list_id
+    ##
+    # @!attribute [r] termtype
+    #   @return [String]
+    attribute :termtype, Types::String
+    ##
+    # @!attribute [r] title
+    #   @return [String]
+    attribute :title, Types::String
+    ##
+    # @!attribute [r] description
+    #   @return [String]
+    attribute :description, Types::String
+    ##
+    # @!attribute [r] num_terms
+    #   @return [Integer]
+    attribute :num_terms, Types::Integer
+    ##
+    # @!attribute [r] privacy
+    #   @return [String]
+    attribute :privacy, Types::String
+
+    ##
+    # Retrieves terms contained in the list.
+    #
+    # @param [Integer, nil] page
+    #
+    # @return [Array<Kanji,Word,Grammar,Sentence>] Depending on the type of list
+    def contents(page: nil)
+      params = { pg: page }.compact
+      body = Renshuu.client.query(:get, "v1/list/#{id}", params:)
+
+      body.dig(:contents, :terms).map { term_class.new(_1) }
+    end
+
+    ##
+    # Adds the given item to the list.
+    #
+    # @param [Listable] item
+    #
+    # @return [Void]
+    # @raise [ArgumentError] If the type of the item does not match the
+    #   list's type
+    #
+    # @see Listable#add_to_list
+    def add(item)
+      unless item.is_a?(term_class)
+        raise ArgumentError, "Expected a `#{term_class}`, got a `#{item.class}`"
+      end
+
+      item.add_to_list(self)
+    end
+
+    ##
+    # Removes the given item from the list.
+    #
+    # @param [Listable] item
+    #
+    # @return [Void]
+    # @raise [ArgumentError] If the type of the item does not match the
+    #   list's type
+    #
+    # @see Listable#remove_from_list
+    def remove(item)
+      unless item.is_a?(term_class)
+        raise ArgumentError, "Expected a `#{term_class}`, got a `#{item.class}`"
+      end
+
+      item.remove_from_list(self)
+    end
+
+    ##
+    # Model class to use for this list's terms.
+    #
+    # @return [Class]
+    # @raise [KeyError]
+    #
+    # @see ::TERMTYPES
+    def term_class
+      @term_class ||= TERMTYPES.fetch(termtype) do |key|
+        raise KeyError, "Unkown list type `#{key}`"
+      end
+    end
+  end
+end

data/lib/renshuu/models/mixins/listable.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Renshuu
+  ##
+  # Mixin for items that can be added to study {List}s.
+  #
+  # = Interface
+  #
+  # This mixin rely on the following interface:
+  #
+  # * +#id+: Identifier of the listable item;
+  # * +.base_route+: Path part used in URL construction.
+  module Listable
+    def self.included(base) # :nodoc:
+      super
+
+      base.extend(ClassMethods)
+    end
+
+    ##
+    # Adds the item to the given list.
+    #
+    # @param [List, String] list
+    #
+    # @return [Void]
+    def add_to_list(list)
+      list_id = case list
+      when List then list.id
+      else list
+      end
+
+      Renshuu.client.query(
+        :put, "v1/#{self.class.base_route}/#{id}", params: { list_id: }
+      )
+    end
+
+    ##
+    # Removes the item from the given list.
+    #
+    # @param [List, String] list
+    #
+    # @return [Void]
+    def remove_from_list(list)
+      list_id = case list
+      when List then list.id
+      else list
+      end
+
+      Renshuu.client.query(
+        :delete, "v1/#{self.class.base_route}/#{id}", params: { list_id: }
+      )
+    end
+
+    ##
+    # Module for class methods provided with the mixin.
+    module ClassMethods
+      ##
+      # Path part used in URL construction.
+      #
+      # Defaults to the class name, demodulized and underscored. Override to
+      # change behavior.
+      #
+      # @return [String]
+      def base_route
+        name.demodulize.underscore
+      end
+    end
+  end
+end

data/lib/renshuu/models/mixins/schedulable.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Renshuu
+  ##
+  # Mixin for items that can be added to study {Schedule}s.
+  #
+  # = Interface
+  #
+  # This mixin rely on the following interface:
+  #
+  # * +#id+: Identifier of the schedulable item;
+  # * +.base_route+: Path part used in URL construction.
+  module Schedulable
+    def self.included(base)
+      super
+
+      base.extend(ClassMethods)
+    end
+
+    ##
+    # Adds the item to the given schedule.
+    #
+    # @param [Schedule, String] schedule
+    #
+    # @return [Void]
+    def add_to_schedule(schedule)
+      sched_id = case schedule
+      when Schedule then schedule.id
+      else schedule
+      end
+
+      Renshuu.client.query(
+        :put, "v1/#{self.class.base_route}/#{id}", params: { sched_id: }
+      )
+    end
+
+    ##
+    # Removes the item from the given schedule.
+    #
+    # @param [Schedule, String] schedule
+    #
+    # @return [Void]
+    def remove_from_schedule(schedule)
+      sched_id = case schedule
+      when Schedule then schedule.id
+      else schedule
+      end
+
+      Renshuu.client.query(
+        :delete, "v1/#{self.class.base_route}/#{id}", params: { sched_id: }
+      )
+    end
+
+    ##
+    # Module for class methods provided with the mixin.
+    module ClassMethods
+      ##
+      # Path part used in URL construction.
+      #
+      # Defaults to the class name, demodulized and underscored. Override to
+      # change behavior.
+      #
+      # @return [String]
+      def base_route
+        name.demodulize.underscore
+      end
+    end
+  end
+end

data/lib/renshuu/models/model.rb

@@ -3,13 +3,7 @@
 module Renshuu
   ##
   # Base class for model objects.
-  class Model < RecursiveOpenStruct
-    ##
-    # Default options for new objects.
-    #
-    # @return [Hash{Symbol => Object}]
-    def self.default_options
-      super.merge(raise_on_missing: true, recurse_over_arrays: true)
-    end
+  class Model < Dry::Struct
+    transform_keys { _1.to_s.underscore.to_sym }
   end
 end