rocksky 0.1.0

data/lib/rocksky/resources/artist.rb

@@ -0,0 +1,40 @@
+module Rocksky
+  module Resources
+    # `app.rocksky.artist.*` endpoints.
+    class Artist < Base
+      # Fetch an artist by AT-URI.
+      def get_artist(uri:)
+        query("app.rocksky.artist.getArtist", uri: uri)
+      end
+
+      # List artists. `names` may be an Array of strings; it will be joined CSV-style.
+      def get_artists(limit: nil, offset: nil, names: nil, genre: nil)
+        query("app.rocksky.artist.getArtists",
+              limit: limit, offset: offset, names: names, genre: genre)
+      end
+
+      # Albums by an artist.
+      def get_artist_albums(uri:)
+        query("app.rocksky.artist.getArtistAlbums", uri: uri)
+      end
+
+      # Tracks by an artist.
+      def get_artist_tracks(uri:, limit: nil, offset: nil)
+        query("app.rocksky.artist.getArtistTracks",
+              uri: uri, limit: limit, offset: offset)
+      end
+
+      # All-time listeners for an artist.
+      def get_artist_listeners(uri:, limit: nil, offset: nil)
+        query("app.rocksky.artist.getArtistListeners",
+              uri: uri, limit: limit, offset: offset)
+      end
+
+      # Recent listeners for an artist.
+      def get_artist_recent_listeners(uri:, limit: nil, offset: nil)
+        query("app.rocksky.artist.getArtistRecentListeners",
+              uri: uri, limit: limit, offset: offset)
+      end
+    end
+  end
+end

data/lib/rocksky/resources/base.rb

@@ -0,0 +1,24 @@
+module Rocksky
+  module Resources
+    # Shared plumbing for resource classes. Each subclass calls {#query} or
+    # {#procedure} with the lexicon NSID; the {Rocksky::HTTP} instance does the
+    # actual transport work.
+    class Base
+      attr_reader :http
+
+      def initialize(http)
+        @http = http
+      end
+
+      protected
+
+      def query(nsid, **params)
+        @http.query(nsid, params)
+      end
+
+      def procedure(nsid, params: {}, body: nil)
+        @http.procedure(nsid, params, body)
+      end
+    end
+  end
+end

data/lib/rocksky/resources/charts.rb

@@ -0,0 +1,33 @@
+module Rocksky
+  module Resources
+    # `app.rocksky.charts.*` endpoints.
+    class Charts < Base
+      # Scrobble chart data.
+      def get_scrobbles_chart(did: nil, artist_uri: nil, album_uri: nil,
+                              song_uri: nil, genre: nil, from: nil, to: nil)
+        query("app.rocksky.charts.getScrobblesChart",
+              did: did,
+              artisturi: artist_uri,
+              albumuri: album_uri,
+              songuri: song_uri,
+              genre: genre,
+              from: from,
+              to: to)
+      end
+
+      # Top artists.
+      def get_top_artists(limit: nil, offset: nil, start_date: nil, end_date: nil)
+        query("app.rocksky.charts.getTopArtists",
+              limit: limit, offset: offset,
+              startDate: start_date, endDate: end_date)
+      end
+
+      # Top tracks.
+      def get_top_tracks(limit: nil, offset: nil, start_date: nil, end_date: nil)
+        query("app.rocksky.charts.getTopTracks",
+              limit: limit, offset: offset,
+              startDate: start_date, endDate: end_date)
+      end
+    end
+  end
+end

data/lib/rocksky/resources/feed.rb

@@ -0,0 +1,51 @@
+module Rocksky
+  module Resources
+    # `app.rocksky.feed.*` endpoints.
+    class Feed < Base
+      # Free-text search across the catalogue.
+      # `q` accepts a positional or `query:` keyword; both map to the lexicon's
+      # `query` parameter.
+      def search(q = nil, query: nil)
+        term = q || query
+        raise ArgumentError, "search needs a query string" if term.nil? || term.empty?
+
+        @http.query("app.rocksky.feed.search", query: term)
+      end
+
+      # List feed generators.
+      def get_feed_generators(size: nil)
+        query("app.rocksky.feed.getFeedGenerators", size: size)
+      end
+
+      # Fetch a feed generator by URI.
+      def get_feed_generator(feed:)
+        query("app.rocksky.feed.getFeedGenerator", feed: feed)
+      end
+
+      # Fetch feed contents.
+      def get_feed(feed:, limit: nil, cursor: nil)
+        query("app.rocksky.feed.getFeed", feed: feed, limit: limit, cursor: cursor)
+      end
+
+      # Stories (recent highlights).
+      def get_stories(size: nil)
+        query("app.rocksky.feed.getStories", size: size)
+      end
+
+      # Track recommendations for an actor.
+      def get_recommendations(did:, limit: nil)
+        query("app.rocksky.feed.getRecommendations", did: did, limit: limit)
+      end
+
+      # Artist recommendations for an actor.
+      def get_artist_recommendations(did:, limit: nil)
+        query("app.rocksky.feed.getArtistRecommendations", did: did, limit: limit)
+      end
+
+      # Album recommendations for an actor.
+      def get_album_recommendations(did:, limit: nil)
+        query("app.rocksky.feed.getAlbumRecommendations", did: did, limit: limit)
+      end
+    end
+  end
+end

data/lib/rocksky/resources/graph.rb

@@ -0,0 +1,34 @@
+module Rocksky
+  module Resources
+    # `app.rocksky.graph.*` endpoints.
+    class Graph < Base
+      # Follow an account. `account` is a DID or handle.
+      def follow_account(account:)
+        procedure("app.rocksky.graph.followAccount", params: { account: account })
+      end
+
+      # Unfollow an account.
+      def unfollow_account(account:)
+        procedure("app.rocksky.graph.unfollowAccount", params: { account: account })
+      end
+
+      # Followers of an actor. `dids` may be a list; it will be CSV-encoded.
+      def get_followers(actor:, limit: nil, dids: nil, cursor: nil)
+        query("app.rocksky.graph.getFollowers",
+              actor: actor, limit: limit, dids: dids, cursor: cursor)
+      end
+
+      # Accounts an actor follows.
+      def get_follows(actor:, limit: nil, dids: nil, cursor: nil)
+        query("app.rocksky.graph.getFollows",
+              actor: actor, limit: limit, dids: dids, cursor: cursor)
+      end
+
+      # Followers of an actor that the viewer also knows.
+      def get_known_followers(actor:, limit: nil, cursor: nil)
+        query("app.rocksky.graph.getKnownFollowers",
+              actor: actor, limit: limit, cursor: cursor)
+      end
+    end
+  end
+end

data/lib/rocksky/resources/like.rb

@@ -0,0 +1,26 @@
+module Rocksky
+  module Resources
+    # `app.rocksky.like.*` endpoints. All require an authenticated client.
+    class Like < Base
+      # Like a song.
+      def like_song(uri:)
+        procedure("app.rocksky.like.likeSong", body: { uri: uri })
+      end
+
+      # Remove a like on a song.
+      def dislike_song(uri:)
+        procedure("app.rocksky.like.dislikeSong", body: { uri: uri })
+      end
+
+      # Like a shout.
+      def like_shout(uri:)
+        procedure("app.rocksky.like.likeShout", body: { uri: uri })
+      end
+
+      # Remove a like on a shout.
+      def dislike_shout(uri:)
+        procedure("app.rocksky.like.dislikeShout", body: { uri: uri })
+      end
+    end
+  end
+end

data/lib/rocksky/resources/mirror.rb

@@ -0,0 +1,22 @@
+module Rocksky
+  module Resources
+    # `app.rocksky.mirror.*` endpoints. Require an authenticated client.
+    class Mirror < Base
+      # List configured mirror sources for the authenticated user.
+      def get_mirror_sources
+        query("app.rocksky.mirror.getMirrorSources")
+      end
+
+      # Configure a mirror source (e.g. Last.fm, ListenBrainz).
+      def put_mirror_source(provider:, enabled: nil, external_username: nil, api_key: nil)
+        body = {
+          provider: provider,
+          enabled: enabled,
+          externalUsername: external_username,
+          apiKey: api_key
+        }.compact
+        procedure("app.rocksky.mirror.putMirrorSource", body: body)
+      end
+    end
+  end
+end

data/lib/rocksky/resources/player.rb

@@ -0,0 +1,73 @@
+module Rocksky
+  module Resources
+    # `app.rocksky.player.*` endpoints — remote control of a Rocksky player.
+    class Player < Base
+      # Currently playing track.
+      def get_currently_playing(player_id: nil, actor: nil)
+        query("app.rocksky.player.getCurrentlyPlaying",
+              playerId: player_id, actor: actor)
+      end
+
+      # Playback queue.
+      def get_playback_queue(player_id: nil)
+        query("app.rocksky.player.getPlaybackQueue", playerId: player_id)
+      end
+
+      # Resume playback.
+      def play(player_id: nil)
+        procedure("app.rocksky.player.play", params: { playerId: player_id })
+      end
+
+      # Pause playback.
+      def pause(player_id: nil)
+        procedure("app.rocksky.player.pause", params: { playerId: player_id })
+      end
+
+      # Skip to next track.
+      def next(player_id: nil)
+        procedure("app.rocksky.player.next", params: { playerId: player_id })
+      end
+
+      # Go to previous track.
+      def previous(player_id: nil)
+        procedure("app.rocksky.player.previous", params: { playerId: player_id })
+      end
+
+      # Seek to position in milliseconds.
+      def seek(position:, player_id: nil)
+        procedure("app.rocksky.player.seek",
+                  params: { playerId: player_id, position: position })
+      end
+
+      # Play a single file.
+      def play_file(file_id:, player_id: nil)
+        procedure("app.rocksky.player.playFile",
+                  params: { playerId: player_id, fileId: file_id })
+      end
+
+      # Play a directory.
+      def play_directory(directory_id:, player_id: nil, shuffle: nil,
+                         recurse: nil, position: nil)
+        procedure("app.rocksky.player.playDirectory",
+                  params: {
+                    playerId: player_id,
+                    directoryId: directory_id,
+                    shuffle: shuffle,
+                    recurse: recurse,
+                    position: position
+                  })
+      end
+
+      # Append items to the queue. `items` is an Array of file identifiers.
+      def add_items_to_queue(items:, player_id: nil, position: nil, shuffle: nil)
+        procedure("app.rocksky.player.addItemsToQueue",
+                  params: {
+                    playerId: player_id,
+                    items: items,
+                    position: position,
+                    shuffle: shuffle
+                  })
+      end
+    end
+  end
+end

data/lib/rocksky/resources/playlist.rb

@@ -0,0 +1,45 @@
+module Rocksky
+  module Resources
+    # `app.rocksky.playlist.*` endpoints.
+    class Playlist < Base
+      # Fetch a playlist.
+      def get_playlist(uri:)
+        query("app.rocksky.playlist.getPlaylist", uri: uri)
+      end
+
+      # List playlists.
+      def get_playlists(limit: nil, offset: nil)
+        query("app.rocksky.playlist.getPlaylists", limit: limit, offset: offset)
+      end
+
+      # Create a playlist.
+      def create_playlist(name:, description: nil)
+        procedure("app.rocksky.playlist.createPlaylist",
+                  params: { name: name, description: description })
+      end
+
+      # Remove a playlist.
+      def remove_playlist(uri:)
+        procedure("app.rocksky.playlist.removePlaylist", params: { uri: uri })
+      end
+
+      # Start a playlist.
+      def start_playlist(uri:, shuffle: nil, position: nil)
+        procedure("app.rocksky.playlist.startPlaylist",
+                  params: { uri: uri, shuffle: shuffle, position: position })
+      end
+
+      # Insert files into a playlist.
+      def insert_files(uri:, files:, position: nil)
+        procedure("app.rocksky.playlist.insertFiles",
+                  params: { uri: uri, files: files, position: position })
+      end
+
+      # Insert a directory into a playlist.
+      def insert_directory(uri:, directory:, position: nil)
+        procedure("app.rocksky.playlist.insertDirectory",
+                  params: { uri: uri, directory: directory, position: position })
+      end
+    end
+  end
+end

data/lib/rocksky/resources/scrobble.rb

@@ -0,0 +1,36 @@
+module Rocksky
+  module Resources
+    # `app.rocksky.scrobble.*` endpoints.
+    class Scrobble < Base
+      # Create a new scrobble. Requires an authenticated client.
+      #
+      # Required: `title`, `artist`. Everything else is optional metadata that
+      # gets forwarded as-is to the lexicon's createScrobble body. Extra fields
+      # may be passed via `**extra`.
+      #
+      # Example:
+      #
+      #   client.scrobble.create_scrobble(
+      #     title: "In Bloom",
+      #     artist: "Nirvana",
+      #     album: "Nevermind",
+      #     timestamp: Time.now.to_i
+      #   )
+      def create_scrobble(title:, artist:, **extra)
+        body = { title: title, artist: artist }.merge(extra).compact
+        procedure("app.rocksky.scrobble.createScrobble", body: body)
+      end
+
+      # Fetch a scrobble by URI.
+      def get_scrobble(uri:)
+        query("app.rocksky.scrobble.getScrobble", uri: uri)
+      end
+
+      # List scrobbles.
+      def get_scrobbles(did: nil, following: nil, limit: nil, offset: nil)
+        query("app.rocksky.scrobble.getScrobbles",
+              did: did, following: following, limit: limit, offset: offset)
+      end
+    end
+  end
+end

data/lib/rocksky/resources/shout.rb

@@ -0,0 +1,58 @@
+module Rocksky
+  module Resources
+    # `app.rocksky.shout.*` endpoints.
+    class Shout < Base
+      # Create a shout.
+      def create_shout(message:, **extra)
+        body = { message: message }.merge(extra).compact
+        procedure("app.rocksky.shout.createShout", body: body)
+      end
+
+      # Reply to a shout.
+      def reply_shout(shout_id:, message:)
+        procedure("app.rocksky.shout.replyShout",
+                  body: { shoutId: shout_id, message: message })
+      end
+
+      # Remove a shout.
+      def remove_shout(id:)
+        procedure("app.rocksky.shout.removeShout", params: { id: id })
+      end
+
+      # Report a shout.
+      def report_shout(shout_id:, reason:)
+        procedure("app.rocksky.shout.reportShout",
+                  body: { shoutId: shout_id, reason: reason })
+      end
+
+      # Shouts on a profile.
+      def get_profile_shouts(did:, limit: nil, offset: nil)
+        query("app.rocksky.shout.getProfileShouts",
+              did: did, limit: limit, offset: offset)
+      end
+
+      # Shouts on an album.
+      def get_album_shouts(uri:, limit: nil, offset: nil)
+        query("app.rocksky.shout.getAlbumShouts",
+              uri: uri, limit: limit, offset: offset)
+      end
+
+      # Shouts on an artist.
+      def get_artist_shouts(uri:, limit: nil, offset: nil)
+        query("app.rocksky.shout.getArtistShouts",
+              uri: uri, limit: limit, offset: offset)
+      end
+
+      # Shouts on a track.
+      def get_track_shouts(uri:)
+        query("app.rocksky.shout.getTrackShouts", uri: uri)
+      end
+
+      # Replies to a shout.
+      def get_shout_replies(uri:, limit: nil, offset: nil)
+        query("app.rocksky.shout.getShoutReplies",
+              uri: uri, limit: limit, offset: offset)
+      end
+    end
+  end
+end

data/lib/rocksky/resources/song.rb

@@ -0,0 +1,38 @@
+module Rocksky
+  module Resources
+    # `app.rocksky.song.*` endpoints.
+    class Song < Base
+      # Fetch a song by URI, MusicBrainz id, ISRC, or Spotify id.
+      def get_song(uri: nil, mbid: nil, isrc: nil, spotify_id: nil)
+        query("app.rocksky.song.getSong",
+              uri: uri, mbid: mbid, isrc: isrc, spotifyId: spotify_id)
+      end
+
+      # List songs.
+      def get_songs(limit: nil, offset: nil, genre: nil,
+                    mbid: nil, isrc: nil, spotify_id: nil)
+        query("app.rocksky.song.getSongs",
+              limit: limit, offset: offset, genre: genre,
+              mbid: mbid, isrc: isrc, spotifyId: spotify_id)
+      end
+
+      # Recent listeners for a song.
+      def get_song_recent_listeners(uri:, limit: nil, offset: nil)
+        query("app.rocksky.song.getSongRecentListeners",
+              uri: uri, limit: limit, offset: offset)
+      end
+
+      # Find an existing song by metadata.
+      def match_song(title:, artist:, mb_id: nil, isrc: nil)
+        query("app.rocksky.song.matchSong",
+              title: title, artist: artist, mbId: mb_id, isrc: isrc)
+      end
+
+      # Create a song.
+      def create_song(title:, artist:, **extra)
+        body = { title: title, artist: artist }.merge(extra).compact
+        procedure("app.rocksky.song.createSong", body: body)
+      end
+    end
+  end
+end

data/lib/rocksky/resources/spotify.rb

@@ -0,0 +1,37 @@
+module Rocksky
+  module Resources
+    # `app.rocksky.spotify.*` endpoints — Spotify remote control for the
+    # authenticated user.
+    class Spotify < Base
+      # Currently playing on Spotify.
+      def get_currently_playing(actor: nil)
+        query("app.rocksky.spotify.getCurrentlyPlaying", actor: actor)
+      end
+
+      # Resume Spotify playback.
+      def play
+        procedure("app.rocksky.spotify.play")
+      end
+
+      # Pause Spotify playback.
+      def pause
+        procedure("app.rocksky.spotify.pause")
+      end
+
+      # Skip to next track.
+      def next
+        procedure("app.rocksky.spotify.next")
+      end
+
+      # Go to previous track.
+      def previous
+        procedure("app.rocksky.spotify.previous")
+      end
+
+      # Seek to position in milliseconds.
+      def seek(position:)
+        procedure("app.rocksky.spotify.seek", params: { position: position })
+      end
+    end
+  end
+end

data/lib/rocksky/resources/stats.rb

@@ -0,0 +1,16 @@
+module Rocksky
+  module Resources
+    # `app.rocksky.stats.*` endpoints.
+    class Stats < Base
+      # Per-user stats.
+      def get_stats(did:)
+        query("app.rocksky.stats.getStats", did: did)
+      end
+
+      # Year-in-review ("Wrapped") data.
+      def get_wrapped(did:, year: nil)
+        query("app.rocksky.stats.getWrapped", did: did, year: year)
+      end
+    end
+  end
+end

data/lib/rocksky/version.rb

@@ -0,0 +1,3 @@
+module Rocksky
+  VERSION = "0.1.0".freeze
+end

data/lib/rocksky.rb

@@ -0,0 +1,32 @@
+require "rocksky/version"
+require "rocksky/error"
+require "rocksky/http"
+require "rocksky/resources/base"
+require "rocksky/resources/actor"
+require "rocksky/resources/album"
+require "rocksky/resources/apikey"
+require "rocksky/resources/artist"
+require "rocksky/resources/charts"
+require "rocksky/resources/feed"
+require "rocksky/resources/graph"
+require "rocksky/resources/like"
+require "rocksky/resources/mirror"
+require "rocksky/resources/player"
+require "rocksky/resources/playlist"
+require "rocksky/resources/scrobble"
+require "rocksky/resources/shout"
+require "rocksky/resources/song"
+require "rocksky/resources/spotify"
+require "rocksky/resources/stats"
+require "rocksky/client"
+
+module Rocksky
+  # Build a new Rocksky client.
+  #
+  #   client = Rocksky.new(token: ENV["ROCKSKY_TOKEN"])
+  #
+  # See {Rocksky::Client#initialize} for all options.
+  def self.new(**opts)
+    Client.new(**opts)
+  end
+end

data/rocksky.gemspec

@@ -0,0 +1,41 @@
+require_relative "lib/rocksky/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "rocksky"
+  spec.version     = Rocksky::VERSION
+  spec.authors     = ["Rocksky"]
+  spec.email       = ["hi@rocksky.app"]
+
+  spec.summary     = "Ruby client for the Rocksky XRPC API."
+  spec.description = "Idiomatic Ruby SDK for Rocksky (rocksky.app) — scrobbles, " \
+                     "shouts, charts, playlists, and more."
+  spec.homepage    = "https://github.com/tsirysndr/rocksky"
+  spec.license     = "MIT"
+
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata = {
+    "homepage_uri"      => spec.homepage,
+    "source_code_uri"   => "https://github.com/tsirysndr/rocksky/tree/main/sdk/ruby",
+    "bug_tracker_uri"   => "https://github.com/tsirysndr/rocksky/issues",
+    "documentation_uri" => "https://docs.rocksky.app",
+    "rubygems_mfa_required" => "true"
+  }
+
+  spec.files = Dir[
+    "lib/**/*.rb",
+    "exe/*",
+    "*.gemspec",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ]
+  spec.require_paths = ["lib"]
+  spec.bindir        = "exe"
+  spec.executables   = Dir["exe/*"].map { |f| File.basename(f) }
+
+  spec.add_development_dependency "irb", "~> 1.11"
+  spec.add_development_dependency "minitest", "~> 5.20"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "webmock", "~> 3.19"
+end