drum 0.1.12

data/lib/drum/model/album.rb

@@ -0,0 +1,114 @@
+module Drum
+  # A album, i.e. a composition of tracks by an artist.
+  #
+  # @!attribute id
+  #  @return [String] The (internal) id of the album
+  # @!attribute name
+  #  @return [String] The name of the album
+  # @!attribute artist_ids
+  #  @return [Array<String>] The artist ids of the album
+  # @!attribute spotify
+  #  @return [optional, AlbumSpotify] Spotify-specific metadata
+  # @!attribute applemusic
+  #  @return [optional, AlbumAppleMusic] Apple Music-specific metadata
+  Album = Struct.new(
+    :id,
+    :name,
+    :artist_ids,
+    :spotify, :applemusic,
+    keyword_init: true
+  ) do
+    def initialize(*)
+      super
+      self.artist_ids ||= []
+    end
+
+    # Parses an album from a nested Hash that uses string keys.
+    #
+    # @param [Hash<String, Object>] h The Hash to be parsed
+    # @return [Album] The parsed album
+    def self.deserialize(h)
+      Album.new(
+        id: h['id'],
+        name: h['name'],
+        artist_ids: h['artist_ids'],
+        spotify: h['spotify'].try { |s| AlbumSpotify.deserialize(s) },
+        applemusic: h['applemusic'].try { |s| AlbumAppleMusic.deserialize(s) }
+      )
+    end
+
+    # Serializes the album to a nested Hash that uses string keys.
+    #
+    # @return [Hash<String, Object>] The serialized representation
+    def serialize
+      {
+        'id' => self.id,
+        'name' => self.name,
+        'artist_ids' => self.artist_ids,
+        'spotify' => self.spotify&.serialize,
+        'applemusic' => self.applemusic&.serialize
+      }.compact
+    end
+  end
+
+  # Spotify-specific metadata about the album.
+  #
+  # @!attribute id
+  #   @return [String] The id of the album on Spotify
+  # @!attribute image_url
+  #   @return [String] The URL of the album cover art on Spotify
+  AlbumSpotify = Struct.new(
+    :id,
+    :image_url,
+    keyword_init: true
+  ) do
+    # Parses spotify metadata from a Hash that uses string keys.
+    #
+    # @param [Hash<String, Object>] h The Hash to be parsed
+    # @return [AlbumSpotify] The parsed metadata
+    def self.deserialize(h)
+      AlbumSpotify.new(
+        id: h['id'],
+        image_url: h['image_url']
+      )
+    end
+
+    # Serializes the metadata to a Hash that uses string keys.
+    #
+    # @return [Hash<String, Object>] The serialized representation
+    def serialize
+      {
+        'id' => self.id,
+        'image_url' => self.image_url
+      }.compact
+    end
+  end
+
+  # Apple Music-specific metadata about the album.
+  #
+  # @!attribute image_url
+  #   @return [optional, String] The cover image of the album
+  AlbumAppleMusic = Struct.new(
+    :image_url,
+    keyword_init: true
+  ) do
+    # Parses Apple Music metadata from a Hash that uses string keys.
+    #
+    # @param [Hash<String, Object>] h The Hash to be parsed
+    # @return [AlbumAppleMusic] The parsed metadata
+    def self.deserialize(h)
+      AlbumAppleMusic.new(
+        image_url: h['image_url']
+      )
+    end
+
+    # Serializes the metadata to a Hash that uses string keys.
+    #
+    # @return [Hash<String, Object>] The serialized representation
+    def serialize
+      {
+        'image_url' => self.image_url
+      }.compact
+    end
+  end
+end

data/lib/drum/model/artist.rb

@@ -0,0 +1,72 @@
+module Drum
+  # An artist.
+  #
+  # @!attribute id
+  #  @return [String] The (internal) id of the artist
+  # @!attribute name
+  #  @return [optional, String] The displayed/formatted name of the artist
+  # @!attribute spotify
+  #  @return [optional, ArtistSpotify] Spotify-specific metadata
+  Artist = Struct.new(
+    :id,
+    :name,
+    :spotify,
+    keyword_init: true
+  ) do
+    # Parses an artist from a nested Hash that uses string keys.
+    #
+    # @param [Hash<String, Object>] h The Hash to be parsed
+    # @return [Artist] The parsed artist
+    def self.deserialize(h)
+      Artist.new(
+        id: h['id'],
+        name: h['name'],
+        spotify: h['spotify'].try { |s| ArtistSpotify.deserialize(s) }
+      )
+    end
+
+    # Serializes the artist to a nested Hash that uses string keys.
+    #
+    # @return [Hash<String, Object>] The serialized representation
+    def serialize
+      {
+        'id' => self.id,
+        'name' => self.name,
+        'spotify' => self.spotify&.serialize
+      }.compact
+    end
+  end
+
+  # Spotify-specific metadata about the artist.
+  #
+  # @!attribute id
+  #   @return [String] The id of the artist on Spotify
+  # @!attribute image_url
+  #   @return [optional, String] An image of the artist
+  ArtistSpotify = Struct.new(
+    :id,
+    :image_url,
+    keyword_init: true
+  ) do
+    # Parses spotify metadata from a Hash that uses string keys.
+    #
+    # @param [Hash<String, Object>] h The Hash to be parsed
+    # @return [ArtistSpotify] The parsed metadata
+    def self.deserialize(h)
+      ArtistSpotify.new(
+        id: h['id'],
+        image_url: h['image_url']
+      )
+    end
+
+    # Serializes the metadata to a Hash that uses string keys.
+    #
+    # @return [Hash<String, Object>] The serialized representation
+    def serialize
+      {
+        'id' => self.id,
+        'image_url' => self.image_url
+      }.compact
+    end
+  end
+end

data/lib/drum/model/playlist.rb

@@ -0,0 +1,222 @@
+require 'drum/utils/ext'
+require 'set'
+
+module Drum
+  # TODO: Smart playlists!
+  # TODO: Add created_at/added_at or similar
+  #       (the Apple Music API provides us with a 'dateAdded', perhaps Spotify has something similar?)
+
+  # A list of tracks with metadata.
+  #
+  # @!attribute id
+  #   @return [String] An internal id for the playlist
+  # @!attribute name
+  #   @return [String] The name of the playlist
+  # @!attribute description
+  #   @return [optional, String] A description of the playlist
+  # @!attribute author_id
+  #   @return [optional, String] The author id
+  # @!attribute path
+  #   @return [optional, Array<String>] The path of parent 'folders' to this playlist.
+  # @!attribute users
+  #   @return [optional, Hash<String, User>] A hash of ids to users used somewhere in the playlist
+  # @!attribute artists
+  #   @return [optional, Hash<String, Artist>] A hash of ids to artists used somewhere in the playlist
+  # @!attribute albums
+  #   @return [optional, Hash<String, Album>] A hash of ids to albums used somewhere in the playlist
+  # @!attribute tracks
+  #   @return [optional, Array<Track>] The list of tracks of the playlist, order matters here
+  # @!attribute spotify
+  #   @return [optional, PlaylistSpotify] Spotify-specific metadata
+  # @!attribute applemusic
+  #   @return [optional, PlaylistAppleMusic] Apple Music-specific metadata
+  class Playlist < Struct.new(
+    :id, :name, :description,
+    :path,
+    :author_id,
+    :users, :artists, :albums, :tracks,
+    :spotify, :applemusic,
+    keyword_init: true
+  )
+    def initialize(*)
+      super
+      self.description ||= ''
+      self.path ||= []
+      self.users ||= {}
+      self.artists ||= {}
+      self.albums ||= {}
+      self.tracks ||= []
+    end
+
+    # TODO: Handle merging in the store_x methods?
+
+    # Stores a user if it does not exist already.
+    #
+    # @param [User] user The user to store.
+    def store_user(user)
+      unless self.users.key?(user.id)
+        self.users[user.id] = user
+      end
+    end
+
+    # Stores an artist if it does not exist already.
+    #
+    # @param [Artist] artist The artist to store.
+    def store_artist(artist)
+      unless self.artists.key?(artist.id)
+        self.artists[artist.id] = artist
+      end
+    end
+
+    # Stores an album if it does not exist already.
+    #
+    # @param [Album] album The album to store.
+    def store_album(album)
+      unless self.albums.key?(album.id)
+        self.albums[album.id] = album
+      end
+    end
+
+    # Stores a track.
+    #
+    # @param [Track] track The track to store.
+    def store_track(track)
+      self.tracks << track
+    end
+
+    # Describes a track in a way useful for song matching by search.
+    #
+    # @return [String] A short description of track name and artists
+    def track_search_phrase(track)
+      "#{track.name} #{track.artist_ids.filter_map { |i| self.artists[i]&.name }.join(' ')}"
+    end
+
+    # Parses a playlist from a nested Hash that uses string keys.
+    #
+    # @param [Hash<String, Object>] h The Hash to be parsed
+    # @return [Playlist] The parsed playlist
+    def self.deserialize(h)
+      Playlist.new(
+        id: h['id'],
+        name: h['name'],
+        description: h['description'],
+        author_id: h['author_id'],
+        path: h['path'],
+        users: h['users']&.map { |u| User.deserialize(u) }&.to_h_by_id,
+        artists: h['artists']&.map { |a| Artist.deserialize(a) }&.to_h_by_id,
+        albums: h['albums']&.map { |a| Album.deserialize(a) }&.to_h_by_id,
+        tracks: h['tracks']&.map { |t| Track.deserialize(t) },
+        spotify: h['spotify'].try { |s| PlaylistSpotify.deserialize(s) },
+        applemusic: h['applemusic'].try { |a| PlaylistAppleMusic.deserialize(a) }
+      )
+    end
+
+    # Serializes the playlist to a nested Hash that uses string keys.
+    #
+    # @return [Hash<String, Object>] The serialized representation
+    def serialize
+      {
+        'id' => self.id,
+        'name' => self.name,
+        'description' => (self.description unless self.description.empty?),
+        'author_id' => self.author_id,
+        'path' => (self.path unless self.path.empty?),
+        'users' => (self.users.each_value.map { |u| u.serialize } unless self.users.empty?),
+        'artists' => (self.artists.each_value.map { |a| a.serialize } unless self.artists.empty?),
+        'albums' => (self.albums.each_value.map { |a| a.serialize } unless self.albums.empty?),
+        'tracks' => (self.tracks.map { |t| t.serialize } unless self.tracks.empty?),
+        'spotify' => self.spotify&.serialize,
+        'applemusic' => self.applemusic&.serialize
+      }.compact
+    end
+  end
+
+  # Spotify-specific metadata about the playlist.
+  #
+  # @!attribute id
+  #   @return [String] The id of the playlist on Spotify
+  # @!attribute public
+  #   @return [optional, Boolean] Whether the playlist is public on Spotify
+  # @!attribute collaborative
+  #   @return [optional, Boolean] Whether the playlist is collaborative on Spotify
+  # @!attribute image_url
+  #   @return [optional, String] The playlist cover URL
+  PlaylistSpotify = Struct.new(
+    :id,
+    :public, :collaborative,
+    :image_url,
+    keyword_init: true
+  ) do
+    # Parses spotify metadata from a Hash that uses string keys.
+    #
+    # @param [Hash<String, Object>] h The Hash to be parsed
+    # @return [PlaylistSpotify] The parsed metadata
+    def self.deserialize(h)
+      PlaylistSpotify.new(
+        id: h['id'],
+        public: h['public'],
+        collaborative: h['collaborative'],
+        image_url: h['image_url']
+      )
+    end
+
+    # Serializes the metadata to a Hash that uses string keys.
+    #
+    # @return [Hash<String, Object>] The serialized representation
+    def serialize
+      {
+        'id' => self.id,
+        'public' => self.public,
+        'collaborative' => self.collaborative,
+        'image_url' => self.image_url
+      }.compact
+    end
+  end
+
+  # TODO: Add image URL to Apple Music metadata?
+
+  # Apple Music-specific metadata about the playlist.
+  #
+  # @!attribute library_id
+  #   @return [optional, String] The library-internal id of the playlist
+  # @!attribute global_id
+  #   @return [optional, String] The global id of the playlist (implies that it is available through the catalog API)
+  # @!attribute public
+  #   @return [optional, Boolean] Whether the playlist is public
+  # @!attribute editable
+  #   @return [optional, Boolean] Whether the playlist is editable
+  # @!attribute image_url
+  #   @return [optional, String] The playlist cover image, if present
+  PlaylistAppleMusic = Struct.new(
+    :library_id, :global_id,
+    :public, :editable, :image_url,
+    keyword_init: true
+  ) do
+    # Parses Apple Music metadata from a Hash that uses string keys.
+    #
+    # @param [Hash<String, Object>] h The Hash to be parsed
+    # @return [PlaylistAppleMusic] The parsed metadata
+    def self.deserialize(h)
+      PlaylistAppleMusic.new(
+        library_id: h['library_id'],
+        global_id: h['global_id'],
+        public: h['public'],
+        editable: h['editable'],
+        image_url: h['image_url']
+      )
+    end
+
+    # Serializes the metadata to a Hash that uses string keys.
+    #
+    # @return [Hash<String, Object>] The serialized representation
+    def serialize
+      {
+        'library_id' => self.library_id,
+        'global_id' => self.global_id,
+        'public' => self.public,
+        'editable' => self.editable,
+        'image_url' => self.image_url
+      }.compact
+    end
+  end
+end

data/lib/drum/model/raw_ref.rb

@@ -0,0 +1,29 @@
+module Drum
+  # A 'half-parsed' reference to a resource, either a token or
+  # something else. The specifics are left to the service-specific
+  # Ref-parser.
+  #
+  # @!attribute raw
+  #   @return [String] The raw text (@-stripped, though, if it's a token)
+  # @!attribute is_token
+  #   @return [Boolean] Whether the ref is a token (i.e. begins with @)
+  RawRef = Struct.new(
+    :text,
+    :is_token,
+    keyword_init: true
+  ) do
+    TOKEN_PREFIX = '@'
+
+    # Parses a RawRef from the given string.
+    #
+    # @param [String] raw The raw string to be parsed
+    # @return [RawRef] The parsed RawRef
+    def self.parse(raw)
+      if raw.start_with?(TOKEN_PREFIX)
+        RawRef.new(text: raw.delete_prefix(TOKEN_PREFIX), is_token: true)
+      else
+        RawRef.new(text: raw, is_token: false)
+      end
+    end
+  end
+end

data/lib/drum/model/ref.rb

@@ -0,0 +1,19 @@
+module Drum
+  # A parsed reference to a resource, usually one or multiple playlists.
+  # Can be a folder, a library or the like, located on the local machine
+  # or a remote service.
+  #
+  # See the README for examples.
+  #
+  # @!attribute service_name
+  #   @return [String] The name of the service
+  # @!attribute resource_type
+  #   @return [Symbol] The type of the resource, service-dependent
+  # @!attribute resource_location
+  #   @return [Object] The path/id of the resource, service-dependent (usually a String or Symbol)
+  Ref = Struct.new(
+    :service_name,
+    :resource_type,
+    :resource_location
+  )
+end

data/lib/drum/model/track.rb

@@ -0,0 +1,157 @@
+
+module Drum
+  # TODO: Add Spotify's audio features
+
+  # A track/song.
+  #
+  # @!attribute name
+  #  @return [String] The name of the track
+  # @!attribute artist_ids
+  #  @return [Array<String>] The (internal) artist ids
+  # @!attribute composer_ids
+  #  @return [optional, Array<String>] The (internal) composer ids
+  # @!attribute genres
+  #  @return [optional, Array<String>] The track's genre names
+  # @!attribute album_id
+  #  @return [optional, String] The (internal) album id
+  # @!attribute duration_ms
+  #  @return [optional, Float] The duration of the track in milliseconds
+  # @!attribute explicit
+  #  @return [optional, Boolean] Whether the track is explicit
+  # @!attribute released_at
+  #  @return [optional, DateTime] The date/time the this track was released
+  # @!attribute added_at
+  #  @return [optional, DateTime] The date/time the this track was added to the playlist
+  # @!attribute added_by
+  #  @return [optional, String] The user id of the user who added this track to the playlist
+  # @!attribute isrc
+  #  @return [optional, String] The International Standard Recording Code of this track
+  # @!attribute spotify
+  #  @return [optional, TrackSpotify] Spotify-specific metadata
+  # @!attribute applemusic
+  #   @return [optional, TrackAppleMusic] Apple Music-specific metadata
+  Track = Struct.new(
+    :name,
+    :artist_ids, :composer_ids, :album_id,
+    :genres,
+    :duration_ms, :explicit,
+    :released_at, :added_at, :added_by,
+    :isrc, :spotify, :applemusic,
+    keyword_init: true
+  ) do
+    def initialize(*)
+      super
+      self.artist_ids ||= []
+      self.composer_ids ||= []
+      self.genres ||= []
+    end
+
+    # Parses a track from a nested Hash that uses string keys.
+    #
+    # @param [Hash<String, Object>] h The Hash to be parsed
+    # @return [Track] The parsed track
+    def self.deserialize(h)
+      Track.new(
+        name: h['name'],
+        artist_ids: h['artist_ids'],
+        composer_ids: h['composer_ids'],
+        genres: h['genres'],
+        album_id: h['album_id'],
+        duration_ms: h['duration_ms'],
+        explicit: h['explicit'],
+        released_at: h['released_at'].try { |d| DateTime.parse(d) },
+        added_at: h['added_at'].try { |d| DateTime.parse(d) },
+        added_by: h['added_by'],
+        isrc: h['isrc'],
+        spotify: h['spotify'].try { |s| TrackSpotify.deserialize(s) },
+        applemusic: h['applemusic'].try { |s| TrackAppleMusic.deserialize(s) }
+      )
+    end
+
+    # Serializes the track to a nested Hash that uses string keys.
+    #
+    # @return [Hash<String, Object>] The serialized representation
+    def serialize
+      {
+        'name' => self.name,
+        'artist_ids' => self.artist_ids,
+        'composer_ids' => (self.composer_ids unless self.composer_ids.empty?),
+        'genres' => (self.genres unless self.genres.empty?),
+        'album_id' => self.album_id,
+        'duration_ms' => self.duration_ms,
+        'explicit' => self.explicit,
+        'released_at' => self.released_at&.iso8601,
+        'added_at' => self.added_at&.iso8601,
+        'added_by' => self.added_by,
+        'isrc' => self.isrc,
+        'spotify' => self.spotify&.serialize,
+        'applemusic' => self.applemusic&.serialize
+      }.compact
+    end
+  end
+
+  # Spotify-specific metadata about the track.
+  #
+  # @!attribute id
+  #   @return [String] The id of the track on Spotify
+  TrackSpotify = Struct.new(
+    :id,
+    keyword_init: true
+  ) do
+    # Parses spotify metadata from a Hash that uses string keys.
+    #
+    # @param [Hash<String, Object>] h The Hash to be parsed
+    # @return [TrackSpotify] The parsed metadata
+    def self.deserialize(h)
+      TrackSpotify.new(
+        id: h['id']
+      )
+    end
+
+    # Serializes the metadata to a Hash that uses string keys.
+    #
+    # @return [Hash<String, Object>] The serialized representation
+    def serialize
+      {
+        'id' => self.id
+      }.compact
+    end
+  end
+
+  # Apple Music-specific metadata about the track.
+  #
+  # @!attribute library_id
+  #   @return [optional, String] The library-internal id of the track
+  # @!attribute catalog_id
+  #   @return [optional, String] The global catalog id of the track
+  # @!attribute preview_url
+  #   @return [optional, String] A short preview of the song audio
+  TrackAppleMusic = Struct.new(
+    :library_id, :catalog_id,
+    :preview_url,
+    keyword_init: true
+  ) do
+    # Parses Apple Music metadata from a Hash that uses string keys.
+    #
+    # @param [Hash<String, Object>] h The Hash to be parsed
+    # @return [TrackAppleMusic] The parsed metadata
+    def self.deserialize(h)
+      TrackAppleMusic.new(
+        library_id: h['library_id'],
+        catalog_id: h['catalog_id'],
+        preview_url: h['preview_url']
+      )
+    end
+
+    # Serializes the metadata to a Hash that uses string keys.
+    #
+    # @return [Hash<String, Object>] The serialized representation
+    def serialize
+      {
+        'library_id' => self.library_id,
+        'catalog_id' => self.catalog_id,
+        'preview_url' => self.preview_url
+      }.compact
+    end
+  end
+end

data/lib/drum/model/user.rb

@@ -0,0 +1,72 @@
+module Drum
+  # A user.
+  #
+  # @!attribute id
+  #   @return [String] The (internal) id of the user
+  # @!attribute display_name
+  #   @return [optional, String] The general formatted name of the user
+  # @!attribute spotify
+  #   @return [optional, UserSpotify] Spotify-specific metadata
+  User = Struct.new(
+    :id,
+    :display_name,
+    :spotify,
+    keyword_init: true
+  ) do
+    # Parses a user from a nested Hash that uses string keys.
+    #
+    # @param [Hash<String, Object>] h The Hash to be parsed
+    # @return [User] The parsed user
+    def self.deserialize(h)
+      User.new(
+        id: h['id'],
+        display_name: h['display_name'],
+        spotify: h['spotify'].try { |s| UserSpotify.deserialize(s) }
+      )
+    end
+
+    # Serializes the user to a nested Hash that uses string keys.
+    #
+    # @return [Hash<String, Object>] The serialized representation
+    def serialize
+      {
+        'id' => self.id,
+        'display_name' => self.display_name,
+        'spotify' => self.spotify&.serialize
+      }.compact
+    end
+  end
+
+  # Spotify-specific metadata about the user.
+  #
+  # @!attribute id
+  #   @return [String] The id of the artist on Spotify
+  # @!attribute image_url
+  #   @return [optional, String] The profile image of the user
+  UserSpotify = Struct.new(
+    :id,
+    :image_url,
+    keyword_init: true
+  ) do
+    # Parses Spotify metadata from a Hash that uses string keys.
+    #
+    # @param [Hash<String, Object>] h The Hash to be parsed
+    # @return [UserSpotify] The parsed user
+    def self.deserialize(h)
+      UserSpotify.new(
+        id: h['id'],
+        image_url: h['image_url']
+      )
+    end
+
+    # Serializes the metadata to a Hash that uses string keys.
+    #
+    # @return [Hash<String, Object>] The serialized representation
+    def serialize
+      {
+        'id' => self.id,
+        'image_url' => self.image_url
+      }.compact
+    end
+  end
+end