apple_music 0.1.0 → 0.2.0

data/lib/apple_music/music_video/relationships.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module AppleMusic
+  class MusicVideo < Resource
+    # https://developer.apple.com/documentation/applemusicapi/musicvideo/relationships
+    class Relationships
+      attr_reader :albums, :artists, :genres
+
+      def initialize(props = {})
+        @albums = Relationship.new(props['albums']).data
+        @artists = Relationship.new(props['artists']).data
+        @genres = Relationship.new(props['genres']).data
+      end
+    end
+
+    self.relationships_model = self::Relationships
+  end
+end

data/lib/apple_music/play_parameters.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module AppleMusic
+  # https://developer.apple.com/documentation/applemusicapi/playparameters
+  class PlayParameters
+    attr_reader :id, :kind
+
+    def initialize(props = {})
+      @id = props['id'] # required
+      @kind = props['kind'] # required
+    end
+  end
+end

data/lib/apple_music/playlist.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module AppleMusic
+  # https://developer.apple.com/documentation/applemusicapi/playlist
+  class Playlist < Resource
+    class << self
+      # e.g. AppleMusic::Playlist.find('pl.acc464c750b94302b8806e5fcbe56e17')
+      # https://developer.apple.com/documentation/applemusicapi/get_a_catalog_playlist
+      def find(id, **options)
+        storefront = Storefront.lookup(options.delete(:storefront))
+        response = AppleMusic.get("catalog/#{storefront}/playlists/#{id}", options)
+        Response.new(response.body).data.first
+      end
+
+      # e.g. AppleMusic::Playlist.list(ids: ['pl.acc464c750b94302b8806e5fcbe56e17', 'pl.97c6f95b0b884bedbcce117f9ea5d54b'])
+      def list(**options)
+        raise ParameterMissing, 'required parameter :ids is missing' unless options[:ids]
+
+        get_collection_by_ids(options.delete(:ids), options)
+      end
+
+      # e.g. AppleMusic::Playlist.get_collection_by_ids(['pl.acc464c750b94302b8806e5fcbe56e17', 'pl.97c6f95b0b884bedbcce117f9ea5d54b'])
+      # https://developer.apple.com/documentation/applemusicapi/get_multiple_catalog_playlists
+      def get_collection_by_ids(ids, **options)
+        ids = ids.is_a?(Array) ? ids.join(',') : ids
+        storefront = Storefront.lookup(options.delete(:storefront))
+        response = AppleMusic.get("catalog/#{storefront}/playlists", options.merge(ids: ids))
+        Response.new(response.body).data
+      end
+
+      # e.g. AppleMusic::Playlist.get_relationship('pl.acc464c750b94302b8806e5fcbe56e17', :curator)
+      # https://developer.apple.com/documentation/applemusicapi/get_a_catalog_playlist_s_relationship_directly_by_name
+      def get_relationship(id, relationship_type, **options)
+        storefront = Storefront.lookup(options.delete(:storefront))
+        response = AppleMusic.get("catalog/#{storefront}/playlists/#{id}/#{relationship_type}", options)
+        Response.new(response.body).data
+      end
+
+      # e.g. AppleMusic::Playlist.related_curator('pl.acc464c750b94302b8806e5fcbe56e17')
+      def related_curator(id, **options)
+        get_relationship(id, :curator, options).first
+      end
+
+      # e.g. AppleMusic::Playlist.related_tracks('pl.acc464c750b94302b8806e5fcbe56e17')
+      def related_tracks(id, **options)
+        get_relationship(id, :tracks, options)
+      end
+
+      def search(term, **options)
+        AppleMusic.search(**options.merge(term: term, types: :playlists)).playlists
+      end
+    end
+  end
+end
+
+require 'apple_music/playlist/attributes'
+require 'apple_music/playlist/relationships'

data/lib/apple_music/playlist/attributes.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module AppleMusic
+  class Playlist < Resource
+    # https://developer.apple.com/documentation/applemusicapi/playlist/attributes
+    class Attributes
+      attr_reader :artwork, :curator_name, :description, :last_modified_date,
+                  :name, :play_params, :playlist_type, :url, :is_chart
+
+      def initialize(props = {})
+        @artwork = Artwork.new(props['artwork']) if props['artwork']
+        @curator_name = props['curatorName']
+        @description = EditorialNotes.new(props['description']) if props['description']
+        @last_modified_date = Date.parse(props['lastModifiedDate']) if props['lastModifiedDate']
+        @name = props['name'] # required
+        @play_params = PlayParameters.new(props['playParams']) if props['playParams']
+        @playlist_type = props['playlistType'] # required
+        @url = props['url'] # required
+        @is_chart = props['isChart']
+      end
+
+      def chart?
+        is_chart
+      end
+
+      def user_shared?
+        playlist_type == 'user-shared'
+      end
+
+      def editorial?
+        playlist_type == 'editorial'
+      end
+
+      def external?
+        playlist_type == 'external'
+      end
+
+      def personal_mix?
+        playlist_type == 'personal-mix'
+      end
+    end
+
+    self.attributes_model = self::Attributes
+  end
+end

data/lib/apple_music/playlist/relationships.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module AppleMusic
+  class Playlist < Resource
+    # https://developer.apple.com/documentation/applemusicapi/playlist/relationships
+    class Relationships
+      attr_reader :curator, :tracks
+
+      def initialize(props = {})
+        @curator = Relationship.new(props['curator']).data.first
+        @tracks = Relationship.new(props['tracks']).data
+      end
+    end
+
+    self.relationships_model = self::Relationships
+  end
+end

data/lib/apple_music/preview.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module AppleMusic
+  # https://developer.apple.com/documentation/applemusicapi/preview
+  class Preview < Resource
+    attr_reader :artwork, :url
+
+    def initialize(props = {})
+      @artwork = Artwork.new(props['artwork']) if props['artwork']
+      @url = props['url'] # required
+    end
+  end
+end

data/lib/apple_music/relationship.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module AppleMusic
+  # https://developer.apple.com/documentation/applemusicapi/relationship
+  class Relationship
+    attr_reader :data, :href, :meta, :next
+
+    def initialize(props = {})
+      props ||= {}
+
+      @data = build_list(props['data'])
+      @href = props['href']
+      @meta = props['meta']
+      @next = props['next']
+    end
+
+    private
+
+    def build_list(data)
+      Array(data).map { |attrs| Resource.build(attrs) }
+    end
+  end
+end

data/lib/apple_music/resource.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module AppleMusic
+  # https://developer.apple.com/documentation/applemusicapi/resource
+  class Resource
+    class InvalidTypeError < StandardError; end
+
+    RESOURCE_MAP = {
+      'activities' => 'AppleMusic::Activity',
+      'albums' => 'AppleMusic::Album',
+      'apple-curators' => 'AppleMusic::AppleCurator',
+      'artists' => 'AppleMusic::Artist',
+      'curators' => 'AppleMusic::Curator',
+      'genres' => 'AppleMusic::Genre',
+      'music-videos' => 'AppleMusic::MusicVideo',
+      'playlists' => 'AppleMusic::Playlist',
+      'songs' => 'AppleMusic::Song',
+      'stations' => 'AppleMusic::Station',
+      'storefronts' => 'AppleMusic::Storefront'
+    }.freeze
+
+    class << self
+      attr_accessor :attributes_model, :relationships_model
+
+      def build(props)
+        class_name = RESOURCE_MAP[props['type']] || raise(InvalidTypeError, "#{props['type']} type is undefined.")
+        const_get(class_name).new(props)
+      end
+    end
+
+    attr_reader :href, :id, :type, :attributes, :relationships
+
+    def initialize(props = {})
+      @href = props['href']
+      @id = props['id']
+      @type = props['type']
+      @attributes = self.class.attributes_model.new(props['attributes']) if props['attributes']
+      @relationships = self.class.relationships_model.new(props['relationships']) if props['relationships']
+    end
+
+    private
+
+    def method_missing(name, *args, &block)
+      if attributes.respond_to?(name)
+        attributes.send(name, *args, &block)
+      elsif relationships.respond_to?(name)
+        relationships.send(name, *args, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      attributes.respond_to?(name, include_private) || relationships.respond_to?(name, include_private)
+    end
+  end
+end

data/lib/apple_music/response.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module AppleMusic
+  # https://developer.apple.com/documentation/applemusicapi/responseroot
+  class Response
+    attr_reader :data, :errors, :href, :meta, :next, :results
+
+    def initialize(props = {})
+      props ||= {}
+      @data = Array(props['data']).map { |attrs| Resource.build(attrs) }
+      @errors = Array(props['errors']).map { |attrs| Error.new(attrs) }
+      @href = props['href']
+      @meta = props['meta']
+      @next = props['next']
+      @results = props['results']
+      raise_api_error unless success?
+    end
+
+    private
+
+    def raise_api_error
+      raise ApiError, errors.map(&:title).join(', ')
+    end
+
+    def success?
+      errors.empty?
+    end
+  end
+end

data/lib/apple_music/search.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module AppleMusic
+  class SearchResponse < Response
+    def initialize(props = {})
+      @results = SearchResult.new(props['results'])
+      super
+    end
+  end
+
+  module Search
+    class << self
+      # e.g. AppleMusic::Search.search(term: 'aaamyyy')
+      # https://developer.apple.com/documentation/applemusicapi/search_for_catalog_resources
+      def search(**options)
+        options[:term] = format_term(options[:term]) if options[:term]
+
+        storefront = Storefront.lookup(options.delete(:storefront))
+        response = AppleMusic.get("catalog/#{storefront}/search", options)
+        SearchResult.new(response.body['results'] || {})
+      end
+
+      # e.g. AppleMusic::Search.search_hints(term: 'aaamyyy')
+      # https://developer.apple.com/documentation/applemusicapi/get_catalog_search_hints
+      def search_hints(**options)
+        options[:term] = format_term(options[:term]) if options[:term]
+        storefront = Storefront.lookup(options.delete(:storefront))
+        response = AppleMusic.get("catalog/#{storefront}/search/hints", options)
+        response.body.dig('results', 'terms') || []
+      end
+
+      private
+
+      def format_term(term)
+        term.is_a?(Array) ? term.join('+') : term
+      end
+    end
+  end
+end

data/lib/apple_music/search_result.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module AppleMusic
+  class SearchResult
+    attr_reader :activities, :albums, :apple_curators, :artists,
+                :curators, :music_videos, :playlists, :songs, :stations
+
+    def initialize(props = {})
+      @activities = Relationship.new(props['activities']).data
+      @albums = Relationship.new(props['albums']).data
+      @apple_curators = Relationship.new(props['apple-curators']).data
+      @artists = Relationship.new(props['artists']).data
+      @curators = Relationship.new(props['curators']).data
+      @music_videos = Relationship.new(props['music-videos']).data
+      @playlists = Relationship.new(props['playlists']).data
+      @songs = Relationship.new(props['songs']).data
+      @stations = Relationship.new(props['stations']).data
+    end
+  end
+end

data/lib/apple_music/song.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module AppleMusic
+  # https://developer.apple.com/documentation/applemusicapi/song
+  class Song < Resource
+    class << self
+      # e.g. AppleMusic::Song.find(900032829)
+      # https://developer.apple.com/documentation/applemusicapi/get_a_catalog_song
+      def find(id, **options)
+        storefront = Storefront.lookup(options.delete(:storefront))
+        response = AppleMusic.get("catalog/#{storefront}/songs/#{id}", options)
+        Response.new(response.body).data.first
+      end
+
+      # e.g. AppleMusic::Song.list(ids: '203709340,201281527')
+      # e.g. AppleMusic::Song.list(isrc: 'NLH851300057')
+      def list(**options)
+        if options[:ids]
+          get_collection_by_ids(options.delete(:ids), options)
+        elsif options[:isrc]
+          get_collection_by_isrc(options.delete(:isrc), options)
+        else
+          raise ParameterMissing, 'required parameter :ids or :isrc is missing'
+        end
+      end
+
+      # e.g. AppleMusic::Song.get_collection_by_ids([203709340, 201281527])
+      # https://developer.apple.com/documentation/applemusicapi/get_multiple_catalog_songs_by_id
+      def get_collection_by_ids(ids, **options)
+        ids = ids.is_a?(Array) ? ids.join(',') : ids
+        storefront = Storefront.lookup(options.delete(:storefront))
+        response = AppleMusic.get("catalog/#{storefront}/songs", options.merge(ids: ids))
+        Response.new(response.body).data
+      end
+
+      # e.g. AppleMusic::Song.get_collection_by_isrc('NLH851300057')
+      # https://developer.apple.com/documentation/applemusicapi/get_multiple_catalog_songs_by_isrc
+      def get_collection_by_isrc(isrc, **options)
+        isrc = isrc.is_a?(Array) ? isrc.join(',') : isrc
+        storefront = Storefront.lookup(options.delete(:storefront))
+        response = AppleMusic.get("catalog/#{storefront}/songs", options.merge('filter[isrc]': isrc))
+        Response.new(response.body).data
+      end
+
+      # e.g. AppleMusic::Song.get_relationship(900032829, :albums)
+      # https://developer.apple.com/documentation/applemusicapi/get_a_catalog_song_s_relationship_directly_by_name
+      def get_relationship(id, relationship_type, **options)
+        storefront = Storefront.lookup(options.delete(:storefront))
+        response = AppleMusic.get("catalog/#{storefront}/songs/#{id}/#{relationship_type}", options)
+        Response.new(response.body).data
+      end
+
+      # e.g. AppleMusic::Song.related_albums(900032829)
+      def related_albums(id, **options)
+        get_relationship(id, :albums, options)
+      end
+
+      # e.g. AppleMusic::Song.related_artists(900032829)
+      def related_artists(id, **options)
+        get_relationship(id, :artists, options)
+      end
+
+      # e.g. AppleMusic::Song.related_genres(900032829)
+      def related_genres(id, **options)
+        get_relationship(id, :genres, options)
+      end
+
+      # e.g. AppleMusic::Song.related_station(900032829)
+      def related_station(id, **options)
+        get_relationship(id, :station, options).first
+      end
+
+      def search(term, **options)
+        AppleMusic.search(**options.merge(term: term, types: :songs)).songs
+      end
+    end
+  end
+end
+
+require 'apple_music/song/attributes'
+require 'apple_music/song/relationships'

data/lib/apple_music/song/attributes.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module AppleMusic
+  class Song < Resource
+    # https://developer.apple.com/documentation/applemusicapi/song/attributes
+    class Attributes
+      attr_reader :album_name, :artist_name, :artwork, :composer_name,
+                  :content_rating, :disc_number, :duration_in_millis,
+                  :editorial_notes, :genre_names, :isrc, :movement_count,
+                  :movement_name, :movement_number, :name, :play_params,
+                  :previews, :release_date, :track_number, :url, :work_name
+
+      def initialize(props = {})
+        @album_name = props['albumName'] # required
+        @artist_name = props['artistName'] # required
+        @artwork = Artwork.new(props['artwork']) # required
+        @composer_name = props['composerName']
+        @content_rating = props['contentRating']
+        @disc_number = props['discNumber'] # required
+        @duration_in_millis = props['durationInMillis']
+        @editorial_notes = EditorialNotes.new(props['editorialNotes']) if props['editorialNotes']
+        @genre_names = props['genreNames'] # required
+        @isrc = props['isrc'] # required
+        @movement_count = props['movementCount']
+        @movement_name = props['movementName']
+        @movement_number = props['movementNumber']
+        @name = props['name'] # required
+        @play_params = PlayParameters.new(props['playParams']) if props['playParams']
+        @previews = Array(props['previews']).map { |attrs| Preview.new(attrs) } # required
+        @release_date = Date.parse(props['releaseDate']) # required
+        @track_number = props['trackNumber'] # required
+        @url = props['url'] # required
+        @work_name = props['workName']
+      end
+    end
+
+    self.attributes_model = self::Attributes
+  end
+end