listenbrainz 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa91d4869adbba2530463a1a70dac945046de4f49701cda50e28fd3d87c243bb
-  data.tar.gz: 921fbcd3b84c5cb3212fc713c8662f31a216784d6c874b5fddba0527c67f5a5b
+  metadata.gz: 24eb87f56c901614053a518a7f89dceac0f6ce6173198c57a589f644b930504c
+  data.tar.gz: 5f5a6f5d788ffcc43cd5eed5419188e3fdf596b3746df72b3791251242c7f506
 SHA512:
-  metadata.gz: 6c32fdddb83cff2bbbcd74f36904ae4d8869cf5718cd4c05f0c6313afa9532b485b888965b828c72660a79316540ccecd670932aa9d30abc3d2ac4b63b47ff78
-  data.tar.gz: 9b11e3008645817ba78d4d00aaa8322057e7d3da3dcfe4c842acdd44da3f46fa80a35b4e6e9f58c8e6be672281c70b6b289774fc0738a96c60748e4036c4b223
+  metadata.gz: f456a05f56fda45159f312cbb75587308879eb301611cb4e28b7039ea5252a3ee50899a7cd35e15d6fc11ab966e0144c036a8fe836925d02d47df859ae3750ec
+  data.tar.gz: 25e5a72d6b0b957482f5cda29a2f7809ff4767ee9f568c8034ad515aa05e09fe148db5f0a623e94a6fc41eff640cfb97b517aa4da1338e862c883e8fda91beda

data/.gitlab/issue_templates/Bug Report.md

@@ -0,0 +1,26 @@
+# Bug report
+
+/label ~bug
+
+## Context
+
+- [ ] Ruby version:
+- [ ] ListenBrainz version:
+
+## Steps to reproduce
+
+- [ ] *Provide a Minimal, Verifiable, Complete Example (MVCE) highlighting the
+  problem.*
+
+```ruby
+# Steps to reproduce
+```
+
+### Expected behavior
+
+- [ ] *Describe what the MVCE should do.*
+
+### Actual behavior
+
+- [ ] *Describe what the MVCE does, and highlight the difference with the
+  expected behavior.*

data/.gitlab/issue_templates/User Story.md

@@ -0,0 +1,20 @@
+# User story
+
+/label ~feature
+
+## Description
+
+- [ ] *Describe the feature and its added value.*
+
+As a user,
+I want to ...
+In order to...
+
+## Definition of Done
+
+- [ ] *Describe the expected outcome of the feature.*
+- [ ] *Include code examples of the expected syntax.*
+
+```ruby
+# Add examples
+```

data/CHANGELOG.md

@@ -8,6 +8,15 @@ The format is based on [Keep a Changelog][kac], and this project adheres to
 [kac]: https://keepachangelog.com/en/1.1.0/
 [semver]: https://semver.org/spec/v2.0.0.html
 
+## [0.2.0] - 2025-02-15
+
+### Added
+
+- Added `Artist`
+- Added `ArtistMap`
+- Added `ReleaseGroup`
+- Added `Recording`
+
 ## [0.1.0] - 2025-01-31
 
 - Initial release

data/README.md

@@ -94,6 +94,66 @@ listen.submit(mode: :playing_now)
 ListenBrainz::Listen.sumbit([listen])
 ```
 
+### Retrieving artists
+
+```ruby
+# Retrieve top artists for the current user
+ListenBrainz::Artist.get
+ListenBrainz::Artist.get(count: 5, offset: 10, range: :this_month)
+
+# Retrieve top artists for a different user
+ListenBrainz::Artist.get('Bobby')
+ListenBrainz::Artist.get('Bobby', count: 5, offset: 10, range: :this_month)
+
+# Retrieve site-wide top artists
+ListenBrainz::Artist.sitewide
+ListenBrainz::Artist.sitewide(count: 5, offset: 10, range: :this_month)
+
+# Retrieve artist map for the current user
+ListenBrainz::ArtistMap.get
+ListenBrainz::ArtistMap.get(range: :this_week)
+
+# Retrieve artist map for a different user
+ListenBrainz::ArtistMap.get('Bobby')
+ListenBrainz::ArtistMap.get('Bobby', range: :this_week)
+
+# Retrieve site-wide artist map
+ListenBrainz::ArtistMap.sitewide
+ListenBrainz::ArtistMap.sitewide(range: :all_time)
+```
+
+### Retrieving release groups
+
+```ruby
+# Retrieve top release groups for the current user
+ListenBrainz::ReleaseGroup.get
+ListenBrainz::ReleaseGroup.get(count: 5, offset: 10, range: :this_month)
+
+# Retrieve top release groups for a different user
+ListenBrainz::ReleaseGroup.get('Bobby')
+ListenBrainz::ReleaseGroup.get('Bobby', count: 5, offset: 10, range: :this_month)
+
+# Retrieve site-wide top release groups
+ListenBrainz::ReleaseGroup.sitewide
+ListenBrainz::ReleaseGroup.sitewide(count: 5, offset: 10, range: :this_year)
+```
+
+### Retrieving recordings
+
+```ruby
+# Retrieve top recordings for the current user
+ListenBrainz::Recording.get
+ListenBrainz::Recording.get(count: 5, offset: 10, range: :all_time)
+
+# Retrieve top recordings for a different user
+ListenBrainz::Recording.get('Bobby')
+ListenBrainz::Recording.get('Bobby', count: 5, offset: 10, range: :all_time)
+
+# Retrieve site-wide top recordings
+ListenBrainz::Recording.sitewide
+ListenBrainz::Recording.sitewide(count: 5, offset: 10, range: :all_time)
+```
+
 ## Documentation
 
 A complete YARD documentation is available below.

data/Rakefile

@@ -11,6 +11,8 @@ RuboCop::RakeTask.new
 
 require 'yard'
 
-YARD::Rake::YardocTask.new
+YARD::Rake::YardocTask.new do |yard|
+  yard.files = ['-', 'CHANGELOG.md']
+end
 
 task default: %i[spec rubocop yard]

data/lib/listenbrainz/models/artist.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module ListenBrainz
+  ##
+  # Model class for artists.
+  #
+  # @see https://rain0r.github.io/listenbrainz-openapi/index.html#/lbStats/topArtistsForUser
+  class Artist < Base
+    ##
+    # Retrieves the top artists for a given user.
+    #
+    # @param [String] username
+    # @param [Integer, nil] count Number of artists to retrieve
+    # @param [Integer, nil] offset Number of artists to skip
+    # @param [Symbol, nil] range +all_time+, +month+, +week+, +year+, +quarter+,
+    #   +half_yearly+, +this_week+, +this_month+ or +this_year+
+    #
+    # @return [Payload]
+    def self.get(
+      username = ListenBrainz.client.username, count: nil, offset: nil,
+      range: nil
+    )
+      params = { count:, offset:, range: }.compact
+      ListenBrainz.client.query(
+        :get, "1/stats/user/#{username}/artists", params:
+      ).fetch(:payload).then { Payload.new(_1) }
+    end
+
+    ##
+    # Retrieves site-wide top artists.
+    #
+    # @param [Integer, nil] count Number of artists to retrieve
+    # @param [Integer, nil] offset Number of artists to skip
+    # @param [Symbol, nil] range +all_time+, +month+, +week+, +year+, +quarter+,
+    #   +half_yearly+, +this_week+, +this_month+ or +this_year+
+    #
+    # @return [Payload]
+    def self.sitewide(count: nil, offset: nil, range: nil)
+      params = { count:, offset:, range: }.compact
+      payload = ListenBrainz.client.query(
+        :get, '1/stats/sitewide/artists', params:
+      ).fetch(:payload)
+
+      # HACK: API is not consistent between site-wide and user schema.
+      payload[:total_artist_count] = payload[:count]
+      Payload.new(payload)
+    end
+
+    ##
+    # Model class for artist payloads.
+    #
+    # Contains the actual artists as well as additional metadata.
+    class Payload < Base
+      ##
+      # @!attribute [r] from_ts
+      #   @return [Time]
+      attribute :from_ts, Types::Timestamp
+      ##
+      # @!attribute [r] to_ts
+      #   @return [Time]
+      attribute :to_ts, Types::Timestamp
+      ##
+      # @!attribute [r] total_artist_count
+      #   @return [Integer]
+      attribute :total_artist_count, Types::Integer
+
+      ##
+      # @!attribute [r] artists
+      #   @return [Array<Artist>]
+      attribute :artists, Types::Array.of(Artist)
+    end
+
+    ##
+    # @!attribute [r] artist_mbid
+    #   @return [String, nil]
+    attribute? :artist_mbid, Types::String.optional
+    alias mbid artist_mbid
+    ##
+    # @!attribute [r] artist_name
+    #   @return [String]
+    attribute :artist_name, Types::String
+    alias name artist_name
+    ##
+    # @!attribute [r] listen_count
+    #   @return [Integer]
+    attribute :listen_count, Types::Integer
+  end
+end

data/lib/listenbrainz/models/artist_map.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module ListenBrainz
+  ##
+  # Model class for artist maps.
+  class ArtistMap < Base
+    ##
+    # Retrieves the artist map for the given user.
+    #
+    # @param [String] username
+    # @param [Symbol, nil] range
+    #
+    # @return [Payload]
+    #
+    # @see https://rain0r.github.io/listenbrainz-openapi/index.html#/lbStats/artistMapForUser
+    def self.get(username = ListenBrainz.client.username, range: nil)
+      params = { range: }.compact
+
+      ListenBrainz.client.query(
+        :get, "1/stats/user/#{username}/artist-map", params:
+      ).fetch(:payload).then { Payload.new(_1) }
+    end
+
+    ##
+    # Retrieves the site-wide artist map.
+    #
+    # @param [Symbol, nil] range
+    #
+    # @return [Payload]
+    #
+    # @see https://rain0r.github.io/listenbrainz-openapi/index.html#/lbStats/sitewideArtistMap
+    def self.sitewide(range: nil)
+      params = { range: }.compact
+      ListenBrainz.client.query(
+        :get, '1/stats/sitewide/artist-map', params:
+      ).fetch(:payload).then { Payload.new(_1) }
+    end
+
+    ##
+    # Model class for artist map payloads.
+    class Payload < Base
+      ##
+      # @!attribute [r] from_ts
+      #   @return [Time]
+      attribute :from_ts, Types::Timestamp
+      ##
+      # @!attribute [r] last_updated
+      #   @return [Time]
+      attribute :last_updated, Types::Timestamp
+      ##
+      # @!attribute [r] to_ts
+      #   @return [Time]
+      attribute :to_ts, Types::Timestamp
+
+      ##
+      # @!attribute [r] artist_map
+      #   @return [Array<ArtistMap>]
+      attribute :artist_map, Types::Array.of(ArtistMap)
+    end
+
+    ##
+    # @!attribute [r] artist_count
+    #   @return [Integer]
+    attribute :artist_count, Types::Integer
+    ##
+    # @!attribute [r] country
+    #   ISO-3166-1 alpha-3 code of the country
+    #   @return [String]
+    #   @see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
+    attribute :country, Types::String
+    ##
+    # @!attribute [r] listen_count
+    #   @return [Integer]
+    attribute :listen_count, Types::Integer
+
+    ##
+    # @!attribute [r] artists
+    #   @return [Array<Artist>]
+    attribute :artists, Types::Array.of(Artist)
+  end
+end

data/lib/listenbrainz/models/recording.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module ListenBrainz
+  ##
+  # Model class for recordings.
+  class Recording < Base
+    ##
+    # Retrieves the top recordings for the given user.
+    #
+    # @param [String, nil] username
+    # @param [Integer, nil] count
+    # @param [Integer, nil] offset
+    # @param [Symbol, nil] range
+    #
+    # @return [Payload]
+    #
+    # @see https://rain0r.github.io/listenbrainz-openapi/index.html#/lbStats/topRecordingsForUser
+    def self.get(
+      username = ListenBrainz.client.username, count: nil, offset: nil,
+      range: nil
+    )
+      params = { count:, offset:, range: }.compact
+      ListenBrainz.client.query(
+        :get, "1/stats/user/#{username}/recordings", params:
+      ).fetch(:payload).then { Payload.new(_1) }
+    end
+
+    ##
+    # Retrieves the site-wide top recordings.
+    #
+    # @param [Integer, nil] count
+    # @param [Integer, nil] offset
+    # @param [Symbol, nil] range
+    #
+    # @return [Payload]
+    #
+    # @see https://rain0r.github.io/listenbrainz-openapi/index.html#/lbStats/sitewideTopRecordings
+    def self.sitewide(count: nil, offset: nil, range: nil)
+      params = { count:, offset:, range: }.compact
+      ListenBrainz.client.query(:get, '1/stats/sitewide/recordings', params:)
+        .fetch(:payload).then { Payload.new(_1) }
+    end
+
+    ##
+    # Model class for recording payloads.
+    class Payload < Base
+      ##
+      # @!attribute [r] from_ts
+      #   @return [Time]
+      attribute :from_ts, Types::Timestamp
+      ##
+      # @!attribute [r] last_updated
+      #   @return [Time]
+      attribute :last_updated, Types::Timestamp
+      ##
+      # @!attribute [r] to_ts
+      #   @return [Time]
+      attribute :to_ts, Types::Timestamp
+      ##
+      # @!attribute [r] total_recording_count
+      #   @return [Integer, nil]
+      attribute? :total_recording_count, Types::Integer
+
+      ##
+      # @!attribute [r] recordings
+      #   @return [Array<Recording>]
+      attribute :recordings, Types::Array.of(Recording)
+    end
+
+    ##
+    # @!attribute [r] artist_mbids
+    #   @return [Array<String>]
+    attribute :artist_mbids, Types::Array.of(Types::String)
+    ##
+    # @!attribute [r] artist_name
+    #   @return [String]
+    attribute :artist_name, Types::String
+    ##
+    # @!attribute [r] listen_count
+    #   @return [Integer]
+    attribute :listen_count, Types::Integer
+    ##
+    # @!attribute [r] recording_mbid
+    #   @return [String, nil]
+    attribute? :recording_mbid, Types::String.optional
+    alias mbid recording_mbid
+    ##
+    # @!attribute [r] release_mbid
+    #   @return [String]
+    attribute? :release_mbid, Types::String.optional
+    ##
+    # @!attribute [r] release_name
+    #   @return [String]
+    attribute :release_name, Types::String
+    ##
+    # @!attribute [r] track_name
+    #   @return [String]
+    attribute :track_name, Types::String
+    alias name track_name
+  end
+end

data/lib/listenbrainz/models/release_group.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module ListenBrainz
+  ##
+  # Model class for release groups.
+  class ReleaseGroup < Base
+    ##
+    # Retrieves the top release groups for the given user.
+    #
+    # @param [String, nil] username
+    # @param [Integer, nil] count
+    # @param [Integer, nil] offset
+    # @param [Symbol, nil] range
+    #
+    # @return [Payload]
+    #
+    # @see https://rain0r.github.io/listenbrainz-openapi/index.html#/lbStats/topReleaseGroupsForUser
+    def self.get(
+      username = ListenBrainz.client.username, count: nil, offset: nil,
+      range: nil
+    )
+      params = { count:, offset:, range: }.compact
+      ListenBrainz.client.query(
+        :get, "1/stats/user/#{username}/release-groups", params:
+      ).fetch(:payload).then { Payload.new(_1) }
+    end
+
+    ##
+    # Retrieves site-wide top release groups.
+    #
+    # @param [Integer, nil] count
+    # @param [Integer, nil] offset
+    # @param [Symbol, nil] range
+    #
+    # @return [Payload]
+    #
+    # @see https://rain0r.github.io/listenbrainz-openapi/index.html#/lbStats/sitewideTopReleaseGroups
+    def self.sitewide(count: nil, offset: nil, range: nil)
+      params = { count:, offset:, range: }.compact
+      ListenBrainz.client.query(
+        :get, '1/stats/sitewide/release-groups', params:
+      ).fetch(:payload).then { Payload.new(_1) }
+    end
+
+    ##
+    # Model class for release group payloads.
+    class Payload < Base
+      ##
+      # @!attribute [r] from_ts
+      #   @return [Time]
+      attribute :from_ts, Types::Timestamp
+      ##
+      # @!attribute [r] last_updated
+      #   @return [Time]
+      attribute :last_updated, Types::Timestamp
+      ##
+      # @!attribute [r] to_ts
+      #   @return [Time]
+      attribute :to_ts, Types::Timestamp
+
+      ##
+      # @!attribute [r] release_groups
+      #   @return [Array<ReleaseGroup>]
+      attribute :release_groups, Types::Array.of(ReleaseGroup)
+    end
+
+    ##
+    # @!attribute [r] artist_mbids
+    #   @return [Array<String>]
+    attribute :artist_mbids, Types::Array.of(Types::String)
+    ##
+    # @!attribute [r] artist_name
+    #   @return [String]
+    attribute :artist_name, Types::String
+    ##
+    # @!attribute [r] listen_count
+    #   @return [Integer]
+    attribute :listen_count, Types::Integer
+    ##
+    # @!attribute [r] release_group_mbid
+    #   @return [String, nil]
+    attribute? :release_group_mbid, Types::String.optional
+    alias mbid release_group_mbid
+    ##
+    # @!attribute [r] release_group_name
+    #   @return [String, nil]
+    attribute? :release_group_name, Types::String.optional
+    alias name release_group_name
+  end
+end

data/lib/listenbrainz/models.rb

@@ -5,4 +5,9 @@ module ListenBrainz; end # :nodoc:
 require_relative 'models/base'
 require_relative 'models/types'
 
+require_relative 'models/artist'
 require_relative 'models/listen'
+require_relative 'models/recording'
+require_relative 'models/release_group'
+
+require_relative 'models/artist_map'

data/lib/listenbrainz/version.rb

@@ -3,5 +3,5 @@
 module ListenBrainz
   ##
   # Current version of the gem.
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: listenbrainz
 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-02-01 00:00:00.000000000 Z
+date: 2025-02-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-struct
@@ -47,6 +47,8 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".gitlab-ci.yml"
+- ".gitlab/issue_templates/Bug Report.md"
+- ".gitlab/issue_templates/User Story.md"
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
@@ -61,8 +63,12 @@ files:
 - lib/listenbrainz/client.rb
 - lib/listenbrainz/configuration.rb
 - lib/listenbrainz/models.rb
+- lib/listenbrainz/models/artist.rb
+- lib/listenbrainz/models/artist_map.rb
 - lib/listenbrainz/models/base.rb
 - lib/listenbrainz/models/listen.rb
+- lib/listenbrainz/models/recording.rb
+- lib/listenbrainz/models/release_group.rb
 - lib/listenbrainz/models/types.rb
 - lib/listenbrainz/version.rb
 - listenbrainz.code-workspace