renshuu 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 182e63b036401b107a66bf329425dd16dbc35ae63dc0326996ccae79ee95484c
-  data.tar.gz: 2ffe79bf4e6a7d9e22bf15cfe698b88b441a1ef7cfc185e4ee93d0438555ff59
+  metadata.gz: a43b493faf4ee0d7165c0a6a054f04a1f2e50ecb60d81c1e9226bea9c6be3643
+  data.tar.gz: 71e85c4b84336960eddd66b525167528495ba04fb26f340d6a022aa3bf5d5cff
 SHA512:
-  metadata.gz: b480fa63633cdb81180c5703204b8867efa75903f5e9d197df99979064a2fffd5eb314ab01cece8c237dd4cd4826de58d2dd3cbd18700ff0683208b4d869250e
-  data.tar.gz: 0dbf167eb256825633f0cb9069997042e80869e3e58eacb7b42f8cfd25db7cc015e8e356f834d4b586a59239981805481ab4f8d7ec06b85c9240e3a7f83c22c4
+  metadata.gz: a848a7d5c6615157835467a7e564bfe201c13dfbf9f8ffc4ea26d6f15b3f292df68f042f3b0dd352391a8d6ba1577fdd2c68635946cd811aae15ba06b94ad89e
+  data.tar.gz: e3eed0edab20ad32adba4042a6a4d4728c23fceb035ac2ba81704a64952e5aa1ff7ac6026ae2d7ac2bfbc59d6d5cf5aa7ebaa0b73893ecbd16dec7196d33b146

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:

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [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

@@ -61,6 +61,44 @@ 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
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run

data/lib/renshuu/models/grammar.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Renshuu
+  ##
+  # Model class for grammar entries.
+  class Grammar < Model
+    ##
+    # 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)
+
+    ##
+    # @!attribute [r] user_data
+    #   @return [UserData]
+    attribute :user_data, UserData
+  end
+end

data/lib/renshuu/models/kanji.rb

@@ -29,5 +29,131 @@ 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
+
+    ##
+    # Model class for kanji presence.
+    class Presence < Model
+      ##
+      # Model class for kanji schedule presence.
+      class Schedule < Model
+        ##
+        # @!attribute [r] sched_id
+        #   @return [String]
+        attribute :sched_id, Types::String
+        alias schedule_id sched_id
+        ##
+        # @!attribute [r] name
+        #   @return [String]
+        attribute :name, Types::String
+        ##
+        # @!attribute [r] has_word
+        #   @return [Boolean]
+        attribute :has_word, Types::Params::Bool
+      end
+      ##
+      # @!attribute [r] scheds
+      #   @return [Array<Schedule>]
+      attribute :scheds, Types::Array.of(Schedule)
+      alias schedules scheds
+
+      ##
+      # Model class for kanji list presence.
+      class List < Model
+        ##
+        # @!attribute [r] list_id
+        #   @return [String]
+        attribute :list_id, Types::String
+        ##
+        # @!attribute [r] name
+        #   @return [String]
+        attribute :name, Types::String
+        ##
+        # @!attribute [r] set_name
+        #   @return [String, nil]
+        attribute? :set_name, Types::String
+        ##
+        # @!attribute [r] has_word
+        #   @return [Boolean]
+        attribute :has_word, Types::Params::Bool
+      end
+      ##
+      # @!attribute [r] lists
+      #   @return [Array<List>]
+      attribute :lists, Types::Array.of(List)
+    end
+    attribute? :presence, Presence
   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

data/lib/renshuu/models/profile.rb

@@ -12,5 +12,163 @@ module Renshuu
       body = Renshuu.client.query(:get, 'v1/profile')
       new(body)
     end
+
+    ##
+    # @!attribute [r] id
+    #   @return [String]
+    attribute :id, Types::String
+    ##
+    # @!attribute [r] real_name
+    #   @return [String]
+    attribute :real_name, Types::String
+    ##
+    # @!attribute [r] adventure_level
+    #   @return [String]
+    attribute :adventure_level, Types::String
+    ##
+    # @!attribute [r] user_length
+    #   @return [String]
+    attribute :user_length, Types::String
+    ##
+    # @!attribute [r] kao
+    #   @return [URI]
+    attribute :kao, Types::URI
+
+    ##
+    # Model class for user study counts.
+    class StudyCount < Model
+      ##
+      # @!attribute [r] today_all
+      #   @return [Integer]
+      attribute :today_all, Types::Integer
+      ##
+      # @!attribute [r] today_grammar
+      #   @return [Integer]
+      attribute :today_grammar, Types::Integer
+      ##
+      # @!attribute [r] today_vocab
+      #   @return [Integer]
+      attribute :today_vocab, Types::Integer
+      ##
+      # @!attribute [r] today_kanji
+      #   @return [Integer]
+      attribute :today_kanji, Types::Integer
+      ##
+      # @!attribute [r] today_sent
+      #   @return [Integer]
+      attribute :today_sent, Types::Integer
+      ##
+      # @!attribute [r] today_aconj
+      #   @return [Integer]
+      attribute :today_aconj, Types::Integer
+      ##
+      # @!attribute [r] today_conj
+      #   @return [Integer]
+      attribute :today_conj, Types::Integer
+      ##
+      # @!attribute [r] total
+      #   @return [Integer]
+      attribute :total, Types::Integer
+      ##
+      # @!attribute [r] total_vocab
+      #   @return [Integer]
+      attribute :total_vocab, Types::Integer
+      ##
+      # @!attribute [r] total_kanji
+      #   @return [Integer]
+      attribute :total_kanji, Types::Integer
+      ##
+      # @!attribute [r] total_grammar
+      #   @return [Integer]
+      attribute :total_grammar, Types::Integer
+      ##
+      # @!attribute [r] total_sent
+      #   @return [Integer]
+      attribute :total_sent, Types::Integer
+    end
+    ##
+    # @!attribute [r] studied
+    #   @return [StudyCount]
+    attribute :studied, StudyCount
+    alias study_count studied
+
+    ##
+    # Model class for profile JLPT progress.
+    class Progress < Model
+      ##
+      # @!attribute [r] n1
+      #   @return [Integer]
+      attribute :n1, Types::Integer
+      ##
+      # @!attribute [r] n2
+      #   @return [Integer]
+      attribute :n2, Types::Integer
+      ##
+      # @!attribute [r] n3
+      #   @return [Integer]
+      attribute :n3, Types::Integer
+      ##
+      # @!attribute [r] n4
+      #   @return [Integer]
+      attribute :n4, Types::Integer
+      ##
+      # @!attribute [r] n5
+      #   @return [Integer]
+      attribute :n5, Types::Integer
+    end
+    ##
+    # @!attribute [r] level_progress_percs
+    #   @return [Hash{String => Progress}]
+    attribute :level_progress_percs, Types::Hash.map(Types::String, Progress)
+
+    ##
+    # Model class for profile study streaks.
+    class Streak < Model
+      ##
+      # @!attribute [r] correct_in_a_row
+      #   @return [Integer]
+      attribute :correct_in_a_row, Types::Integer
+      ##
+      # @!attribute [r] correct_in_a_row_alltime
+      #   @return [Integer]
+      attribute :correct_in_a_row_alltime, Types::Integer
+      ##
+      # @!attribute [r] days_studied_in_a_row
+      #   @return [Integer]
+      attribute :days_studied_in_a_row, Types::Integer
+      ##
+      # @!attribute [r] days_studied_in_a_row_alltime
+      #   @return [Integer]
+      attribute :days_studied_in_a_row_alltime, Types::Integer
+    end
+    ##
+    # @!attribute [r] streaks
+    #   @return [Hash{String => Streak}]
+    attribute :streaks, Types::Hash.map(Types::String, Streak)
+
+    ##
+    # Model class for profile API usage.
+    class APIUsage < Model
+      ##
+      # @!attribute [r] calls_today
+      #   @return [Integer]
+      attribute :calls_today, Types::Integer
+      ##
+      # @!attribute [r] daily_allowance
+      #   @return [Integer]
+      attribute :daily_allowance, Types::Integer
+
+      ##
+      # Number of API calls remaining in today's quota.
+      #
+      # @return [Integer]
+      def remaining_today
+        daily_allowance - calls_today
+      end
+    end
+    ##
+    # @!attribute [r] api_usage
+    #   @return [APIUsage]
+    attribute :api_usage, APIUsage
   end
 end

data/lib/renshuu/models/sentence.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Renshuu
+  ##
+  # Model class for sentences.
+  #
+  # @see https://api.renshuu.org/docs/#/Sentence
+  class Sentence < Model
+    ##
+    # Searches sentences in Renshuu's dictionary.
+    #
+    # @param [String] value
+    #
+    # @return [Array<Sentence>]
+    #
+    # @see https://api.renshuu.org/docs/#/Sentence/get_reibun_search
+    def self.search(value)
+      Renshuu.client.query(:get, 'v1/reibun/search', params: { value: })
+        .fetch(:reibuns).map { new(_1) }
+    end
+
+    ##
+    # Retrieves sentences from Renshuu's dictionary for a specific word.
+    #
+    # @param [Word, Integer] word
+    #
+    # @return [Array<Sentence>]
+    #
+    # @see https://api.renshuu.org/docs/#/Sentence/get_reibun_search__word_id_
+    def self.word_search(word)
+      identifier = case word
+      when Integer then word
+      else word.id
+      end
+      Renshuu.client.query(:get, "v1/reibun/search/#{identifier}")
+        .fetch(:reibuns).map { new(_1) }
+    end
+
+    ##
+    # @!attribute [r] id
+    #   @return [String]
+    attribute :id, Types::String
+    ##
+    # @!attribute [r] japanese
+    #   @return [String]
+    attribute :japanese, Types::String
+    ##
+    # @!attribute [r] hiragana
+    #   @return [String]
+    attribute :hiragana, Types::String
+    ##
+    # @!attribute [r] meaning
+    #   @return [Hash{String => String}]
+    attribute :meaning, Types::Hash.map(Types::String, Types::String)
+  end
+end

data/lib/renshuu/models/types.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Renshuu
+  ##
+  # Module for type values.
+  module Types
+    include Dry.Types(default: :coercible)
+
+    ##
+    # Dry type for dates.
+    Date = Constructor(::Date) do |date|
+      if date.is_a?(::Date)
+        date
+      elsif date == 'Not yet'
+        nil
+      else
+        ::Date.parse(date)
+      end
+    end
+
+    ##
+    # Dry type for URIs.
+    URI = Constructor(URI) do |uri|
+      ::URI.parse(uri)
+    end
+  end
+end

data/lib/renshuu/models/user_data.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Renshuu
+  ##
+  # Model class for user data.
+  class UserData < Model
+    ##
+    # @!attribute [r] correct_count
+    #   @return [Integer]
+    attribute :correct_count, Types::Integer
+    ##
+    # @!attribute [r] missed_count
+    #   @return [Integer]
+    attribute :missed_count, Types::Integer
+    ##
+    # @!attribute [r] mastery_avg_perc
+    #   @return [Integer]
+    attribute :mastery_avg_perc, Types::Integer
+
+    ##
+    # Model class for user data study vectors.
+    class StudyVector < Model
+      ##
+      # @!attribute [r] name
+      #   @return [String]
+      attribute :name, Types::String
+      ##
+      # @!attribute [r] correct_count
+      #   @return [Integer]
+      attribute :correct_count, Types::Integer
+      ##
+      # @!attribute [r] missed_count
+      #   @return [Integer]
+      attribute :missed_count, Types::Integer
+      ##
+      # @!attribute [r] mastery_perc
+      #   @return [Integer]
+      attribute :mastery_perc, Types::Integer
+      ##
+      # @!attribute [r] last_quizzed
+      #   @return [Date]
+      attribute :last_quizzed, Types::Date
+      ##
+      # @!attribute [r] next_quiz
+      #   @return [Date]
+      attribute :next_quiz, Types::Date
+    end
+    ##
+    # @!attribute [r] study_vectors
+    #   @return [Hash{String => StudyVector}]
+    attribute? :study_vectors, Types::Hash.map(Types::String, StudyVector)
+  end
+end

data/lib/renshuu/models/word.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Renshuu
+  ##
+  # Model class for words and vocabulary.
+  #
+  # @see https://api.renshuu.org/docs/#/Vocabulary
+  class Word < Model
+    ##
+    # Searches the Renshuu vocabulary dictionary.
+    #
+    # @param [String] value
+    #
+    # @return [Array<Word>]
+    def self.search(value)
+      body = Renshuu.client.query(:get, 'v1/word/search', params: { value: })
+
+      body.fetch(:words).map { new(_1) }
+    end
+
+    ##
+    # Retrieves a word from the dictionary by its identifier.
+    #
+    # @param [Integer] id
+    #
+    # @return [Word]
+    def self.get(id)
+      body = Renshuu.client.query(:get, "v1/word/#{id}")
+
+      body.fetch(:words).first.then { new(_1) }
+    end
+
+    ##
+    # @!attribute [r] id
+    #   @return [String]
+    attribute :id, Types::String
+    ##
+    # @!attribute [r] kanji_full
+    #   @return [String]
+    attribute :kanji_full, Types::String
+    ##
+    # @!attribute [r] hiragana_full
+    #   @return [String]
+    attribute :hiragana_full, Types::String
+    ##
+    # @!attribute [r] pic
+    #   @return [Array<URI>, nil]
+    attribute? :pic, Types::Array.of(Types::URI)
+    alias pictures pic
+    ##
+    # @!attribute [r] markers
+    #   @return [Array<String>]
+    attribute :markers, Types::Array.of(Types::String)
+    ##
+    # @!attribute [r] pitch
+    #   @return [Array<String>]
+    attribute :pitch, Types::Array.of(Types::String)
+    ##
+    # @!attribute [r] typeofspeech
+    #   @return [String]
+    attribute :typeofspeech, Types::String
+    alias type_of_speech typeofspeech
+    ##
+    # @!attribute [r] def
+    #   @return [Array<String>]
+    attribute :def, Types::Array.of(Types::String)
+
+    ##
+    # @!attribute [r] user_data
+    #   @return [UserData, nil]
+    attribute? :user_data, UserData
+
+    ##
+    # Retrieves sentences using this word from the dictionary.
+    #
+    # @return [Array<Sentence>]
+    #
+    # @see Sentence.word_search
+    def sentences
+      Sentence.word_search(self)
+    end
+  end
+end

data/lib/renshuu/models.rb

@@ -3,9 +3,17 @@
 module Renshuu # rubocop:disable Style/Documentation
 end
 
+# Types
+require_relative 'models/types'
+
 # Base class
 require_relative 'models/model'
 
-# Other models
+# Other models (respect blank lines for dependency order)
+require_relative 'models/user_data'
+
+require_relative 'models/grammar'
 require_relative 'models/kanji'
 require_relative 'models/profile'
+require_relative 'models/sentence'
+require_relative 'models/word'

data/lib/renshuu/version.rb

@@ -3,5 +3,5 @@
 module Renshuu
   ##
   # Semantic version number of the library.
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/renshuu.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 # External requires
+require 'dry-struct'
 require 'httpx'
-require 'recursive-open-struct'
 require 'uri'
 
 # Pre-module requires

metadata

@@ -1,43 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: renshuu
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Richard Degenne
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-17 00:00:00.000000000 Z
+date: 2025-12-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: httpx
+  name: dry-struct
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '1.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '1.8'
 - !ruby/object:Gem::Dependency
-  name: recursive-open-struct
+  name: httpx
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '1.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '1.5'
 description: Ruby wrapper for the Renshuu API.
 email:
 - hello@richarddegenne.fr
@@ -60,9 +60,14 @@ files:
 - lib/renshuu/client.rb
 - lib/renshuu/configuration.rb
 - lib/renshuu/models.rb
+- lib/renshuu/models/grammar.rb
 - lib/renshuu/models/kanji.rb
 - lib/renshuu/models/model.rb
 - lib/renshuu/models/profile.rb
+- lib/renshuu/models/sentence.rb
+- lib/renshuu/models/types.rb
+- lib/renshuu/models/user_data.rb
+- lib/renshuu/models/word.rb
 - lib/renshuu/version.rb
 - renshuu.code-workspace
 - sample.env