pandoru 0.1.0

data/lib/pandoru/models/station.rb

@@ -0,0 +1,249 @@
+require_relative '_base'
+
+module Pandoru
+  module Models
+    # A single station seed — an artist, song, or genre the station was
+    # built from. Returned under the "music" key of a getStation response
+    # when includeExtendedAttributes is set.
+    class StationSeed < Base
+      field :seed_id, 'seedId'
+      field :music_token, 'musicToken'
+      field :pandora_id, 'pandoraId'
+      field :pandora_type, 'pandoraType'
+      field :genre_name, 'genreName'
+      field :song_name, 'songName'
+      field :artist_name, 'artistName'
+      field :art_url, 'artUrl'
+
+      def song?
+        !song_name.nil?
+      end
+
+      def artist?
+        song_name.nil? && !artist_name.nil?
+      end
+
+      def genre?
+        !genre_name.nil?
+      end
+
+      # Human-readable label, handy for clustering/debugging.
+      def label
+        return genre_name if genre?
+        [artist_name, song_name].compact.join(' - ')
+      end
+    end
+
+    # The seed sets for a station, grouped by kind.
+    class StationSeeds < Base
+      attr_accessor :genres, :songs, :artists
+
+      def self.from_json(api_client, data)
+        return nil unless data
+        instance = new(data, api_client)
+        instance.genres  = StationSeed.from_json_list(api_client, data['genres'])
+        instance.songs   = StationSeed.from_json_list(api_client, data['songs'])
+        instance.artists = StationSeed.from_json_list(api_client, data['artists'])
+        instance
+      end
+
+      # All seeds flattened into one array.
+      def all
+        Array(genres) + Array(artists) + Array(songs)
+      end
+    end
+
+    # A single thumbs-up/down on a song.
+    class SongFeedback < Base
+      field :feedback_id, 'feedbackId'
+      field :song_identity, 'songIdentity'
+      field :is_positive, 'isPositive', type: :boolean
+      field :pandora_id, 'pandoraId'
+      field :album_art_url, 'albumArtUrl'
+      field :music_token, 'musicToken'
+      field :song_name, 'songName'
+      field :artist_name, 'artistName'
+      field :pandora_type, 'pandoraType'
+      date_field :date_created, 'dateCreated'
+
+      def positive?
+        is_positive == true
+      end
+    end
+
+    # A station's feedback (thumbs) returned under the "feedback" key of an
+    # extended getStation response.
+    class StationFeedback < Base
+      attr_accessor :thumbs_up, :thumbs_down
+      field :total_thumbs_up, 'totalThumbsUp'
+      field :total_thumbs_down, 'totalThumbsDown'
+
+      def self.from_json(api_client, data)
+        return nil unless data
+        instance = new(data, api_client)
+        instance.populate_from_json(data)
+        instance.thumbs_up   = SongFeedback.from_json_list(api_client, data['thumbsUp'])
+        instance.thumbs_down = SongFeedback.from_json_list(api_client, data['thumbsDown'])
+        instance
+      end
+    end
+
+    class Station < Base
+      field :station_id, 'stationId'
+      field :station_name, 'stationName' 
+      field :station_token, 'stationToken'
+      field :art_url, 'artUrl'
+      field :detail_url, 'stationDetailUrl'
+      field :sharing_url, 'stationSharingUrl'
+      
+      field :allow_add_music, 'allowAddMusic', type: :boolean
+      field :allow_delete, 'allowDelete', type: :boolean
+      field :allow_rename, 'allowRename', type: :boolean
+      field :allow_edit_description, 'allowEditDescription', type: :boolean
+      
+      field :is_creator, 'isCreator', type: :boolean
+      field :is_shared, 'isShared', type: :boolean
+      field :is_quickmix, 'isQuickMix', type: :boolean
+      field :is_genre_station, 'isGenreStation', type: :boolean
+      field :is_thumbprint, 'isThumbprint', type: :boolean
+      
+      field :thumb_count, 'thumbCount'
+      date_field :date_created, 'dateCreated'
+
+      # Populated only by getStation with includeExtendedAttributes; nil for
+      # stations returned in a getStationList response.
+      attr_accessor :seeds, :feedback
+
+      # Convenience aliases
+      alias_method :id, :station_id
+      alias_method :name, :station_name
+      alias_method :token, :station_token
+
+      def self.from_json(api_client, data)
+        station = super
+        return station unless station && data
+        station.seeds    = StationSeeds.from_json(api_client, data['music'])
+        station.feedback = StationFeedback.from_json(api_client, data['feedback'])
+        station
+      end
+
+      # Seed accessors that are always safe to call (empty array when the
+      # station was loaded without extended attributes).
+      def seed_artists
+        seeds&.artists || []
+      end
+
+      def seed_songs
+        seeds&.songs || []
+      end
+
+      def seed_genres
+        seeds&.genres || []
+      end
+
+      def thumbs_up
+        feedback&.thumbs_up || []
+      end
+
+      def thumbs_down
+        feedback&.thumbs_down || []
+      end
+
+      def get_playlist
+        return nil unless @api_client
+        @api_client.get_playlist(token)
+      end
+
+      def rename(new_name)
+        return false unless allow_rename && @api_client
+        @api_client.rename_station(token, new_name)
+        @name = new_name
+        true
+      end
+
+      def delete
+        return false unless allow_delete && @api_client
+        @api_client.delete_station(token)
+        true
+      end
+
+      def add_seed(music_token)
+        return false unless allow_add_music && @api_client
+        @api_client.add_music(token, music_token)
+        true
+      end
+    end
+
+    class StationList < Collection
+      field :checksum, 'checksum'
+
+      def self.from_json(api_client, data)
+        instance = new(data, api_client)
+        instance.populate_from_json(data)
+        
+        if data['stations']
+          stations = Station.from_json_list(api_client, data['stations'])
+          stations.each { |station| instance << station }
+        end
+        
+        instance
+      end
+
+      def find_by_name(name)
+        find { |station| station.name == name }
+      end
+
+      def quickmix_stations
+        select(&:is_quickmix)
+      end
+
+      def user_stations
+        reject(&:is_quickmix)
+      end
+    end
+
+    class GenreStation < Base
+      field :id, 'stationId'
+      field :name, 'stationName'
+      field :token, 'stationToken'
+      field :category, 'categoryName'
+
+      def create_station
+        return nil unless @api_client
+        @api_client.create_station(search_token: token)
+      end
+    end
+
+    class GenreStationList < Collection
+      field :checksum, 'checksum'
+
+      def self.from_json(api_client, data)
+        instance = new(data, api_client)
+        instance.populate_from_json(data)
+        
+        if data['categories']
+          data['categories'].each do |category|
+            category_name = category['categoryName']
+            next unless category['stations']
+            
+            category['stations'].each do |station_data|
+              station_data['categoryName'] = category_name
+              station = GenreStation.from_json(api_client, station_data)
+              instance << station
+            end
+          end
+        end
+        
+        instance
+      end
+
+      def categories
+        map(&:category).uniq
+      end
+
+      def stations_for_category(category)
+        select { |station| station.category == category }
+      end
+    end
+  end
+end

data/lib/pandoru/models/track_explanation.rb

@@ -0,0 +1,41 @@
+require_relative '_base'
+
+module Pandoru
+  module Models
+    # A single Music-Genome-derived trait from track.explainTrack, e.g.
+    # "electric rock instrumentation" or "a subtle use of vocal harmony".
+    class FocusTrait < Base
+      field :focus_trait_id, 'focusTraitId'
+      field :focus_trait_name, 'focusTraitName'
+
+      def to_s
+        focus_trait_name.to_s
+      end
+    end
+
+    # The result of track.explainTrack: the human-readable traits the Music
+    # Genome Project used to justify playing a track. This is the closest the
+    # API gets to exposing genome data — discrete trait tags, not a vector.
+    class TrackExplanation < Base
+      attr_accessor :explanations
+
+      def self.from_json(api_client, data)
+        return nil unless data
+        instance = new(data, api_client)
+        instance.explanations =
+          FocusTrait.from_json_list(api_client, data['explanations'])
+        instance
+      end
+
+      # The genome-derived trait name strings, with the trailing filler entry
+      # removed. The API always appends a non-attribute entry as the last
+      # explanation ("...many other similarities identified in the Music
+      # Genome Project"); it carries no focusTraitId, so we drop it.
+      def focus_traits
+        traits = explanations || []
+        traits = traits[0...-1] if traits.last && traits.last.focus_trait_id.nil?
+        traits.map(&:focus_trait_name).compact
+      end
+    end
+  end
+end

data/lib/pandoru/models.rb

@@ -0,0 +1,19 @@
+require_relative 'models/_base'
+require_relative 'models/station'
+require_relative 'models/playlist'
+require_relative 'models/search'
+require_relative 'models/bookmark'
+require_relative 'models/track_explanation'
+
+module Pandoru
+  module Models
+    # Convenience method to create models from API responses
+    def self.from_json(model_class, data, api_client = nil)
+      model_class.from_json(data, api_client)
+    end
+
+    def self.from_json_list(model_class, data_list, api_client = nil)
+      model_class.from_json_list(data_list, api_client)
+    end
+  end
+end

data/lib/pandoru/transport.rb

@@ -0,0 +1,395 @@
+# Pandora API Transport
+#
+# This module contains the very low level transport agent for the Pandora API.
+# The transport is concerned with the details of a raw HTTP call to the Pandora
+# API along with the request and response encryption by way of an Encryptor
+# object. The result from a transport is a JSON object for the API or an
+# exception.
+#
+# API consumers should use one of the API clients in the Pandoru::Client package.
+
+require 'faraday'
+require 'faraday/retry'
+require 'json'
+require 'uri'
+require 'time'
+require 'crypt/blowfish'
+require 'base64'
+require 'cgi'
+
+module Pandoru
+  module Transport
+    DEFAULT_API_HOST = "tuner.pandora.com/services/json/"
+
+    # Function decorator implementing retrying logic for handling connection errors
+    module Retries
+      def self.retry_on_error(max_tries = 3, exceptions = [StandardError])
+        lambda do |method|
+          lambda do |*args, &block|
+            attempts = 0
+            begin
+              attempts += 1
+              method.call(*args, &block)
+            rescue *exceptions => e
+              if attempts < max_tries
+                sleep(delay_exponential(0.5, 2, attempts))
+                retry
+              else
+                raise e
+              end
+            end
+          end
+        end
+      end
+
+      def self.delay_exponential(base, growth_factor, attempts)
+        if base == "rand"
+          base = rand
+        elsif base <= 0
+          raise ArgumentError, "Base must be greater than 0"
+        end
+        
+        base * (growth_factor ** (attempts - 1))
+      end
+    end
+
+    # Blowfish cryptography for Pandora API encryption/decryption
+    class BlowfishCryptor
+      BLOCK_SIZE = 8
+
+      def initialize(key)
+        @cipher = Crypt::Blowfish.new(key)
+      end
+
+      def encrypt(data)
+        padded_data = add_padding(data)
+
+        # Encrypt block by block for consistency with decrypt
+        blocks = padded_data.scan(/.{#{BLOCK_SIZE}}/m)
+        encrypted = blocks.map { |block| @cipher.encrypt_block(block) }.join
+
+        encode_hex(encrypted)
+      end
+
+      def decrypt(data, strip_padding: true)
+        return '' if data.empty?
+        decoded_data = decode_hex(data)
+
+        # Decrypt block by block (decrypt_string only does one block!)
+        blocks = decoded_data.scan(/.{#{BLOCK_SIZE}}/m)
+        decrypted = blocks.map { |block| @cipher.decrypt_block(block) }.join
+
+        strip_padding ? self.class.strip_padding(decrypted) : decrypted
+      end
+
+      private
+
+      def add_padding(data)
+        pad_size = BLOCK_SIZE - (data.bytesize % BLOCK_SIZE)
+        padding = pad_size.chr * pad_size
+        data + padding
+      end
+
+      def self.strip_padding(data)
+        pad_size = data[-1].ord
+        computed_padding = pad_size.chr * pad_size
+        
+        raise ArgumentError, "Invalid padding" unless data[-pad_size..-1] == computed_padding
+        
+        data[0...-pad_size]
+      end
+
+      def decode_hex(data)
+        return '' if data.empty?
+        [data.upcase].pack('H*')
+      end
+
+      def encode_hex(data)
+        data.unpack1('H*').downcase.encode('utf-8')
+      end
+    end
+
+    # Pandora Blowfish Encryptor
+    class Encryptor
+      def initialize(decryption_key, encryption_key)
+        @bf_out = BlowfishCryptor.new(encryption_key)
+        @bf_in = BlowfishCryptor.new(decryption_key)
+      end
+
+      def encrypt(data)
+        @bf_out.encrypt(data)
+      end
+
+      def decrypt(data)
+        JSON.parse(@bf_in.decrypt(data))
+      end
+
+      def decrypt_sync_time(data)
+        decrypted = @bf_in.decrypt(data, strip_padding: false)
+        # Extract the sync time (skip first 4 bytes, take all but last 2)
+        # This matches Python's [4:-2] slice
+        time_str = decrypted[4...-2]
+        # The sync time is stored as an ASCII string of the Unix timestamp
+        time_str.to_i
+      end
+    end
+
+    # Pandora API Transport with retries
+    class APITransport
+      API_VERSION = "5"
+
+      REQUIRE_RESET = %w[auth.partnerLogin].freeze
+      NO_ENCRYPT = %w[auth.partnerLogin].freeze
+      REQUIRE_TLS = %w[
+        auth.partnerLogin
+        auth.userLogin
+        station.getPlaylist
+        user.createUser
+      ].freeze
+
+      attr_reader :cryptor, :api_host
+      attr_accessor :partner_auth_token, :user_auth_token, :partner_id, :user_id,
+                    :start_time, :server_sync_time
+
+      def initialize(cryptor = nil, api_host: DEFAULT_API_HOST, proxy: nil)
+        @cryptor = cryptor
+        api_host ||= DEFAULT_API_HOST
+        
+        # Parse host and path
+        if api_host.include?('/services/json')
+          # Extract host from full URL
+          if api_host.include?('://')
+            # Protocol://host format
+            uri_parts = api_host.split('/')
+            @api_host = uri_parts[2]
+          else
+            # host/path format
+            @api_host = api_host.split('/')[0]
+          end
+          @api_path = '/services/json/'
+        else
+          @api_host = api_host
+          @api_path = '/services/json/'
+        end
+        
+        # Set port and TLS based on URL
+        if api_host.include?('https:') || api_host.include?(':443') || api_host == 'tuner.pandora.com'
+          @api_port = 443
+          @api_tls = true
+        else
+          @api_port = 80  
+          @api_tls = false
+        end
+        
+        # Strip protocol from host for compatibility
+        @api_host = @api_host.gsub(%r{^https?://}, '')
+        # Remove path if it got included
+        @api_host = @api_host.split('/')[0]
+        
+        # Extract port from hostname if present
+        if @api_host.include?(':')
+          host_parts = @api_host.split(':')
+          @api_host = host_parts[0]
+          @api_port = host_parts[1].to_i
+          @api_tls = (@api_port == 443)
+        end
+        
+        @encryption_padding = "\x00" * 16
+        @connection = build_connection(proxy)
+        reset
+        @start_time = Time.now.to_f  # Set after reset so it doesn't get cleared
+      end
+
+      def reset
+        @partner_auth_token = nil
+        @user_auth_token = nil
+        @partner_id = nil
+        @user_id = nil
+        @start_time = nil
+        @server_sync_time = nil
+      end
+
+      def set_partner(data)
+        self.sync_time = data["syncTime"]
+        @partner_auth_token = data["partnerAuthToken"]
+        @partner_id = data["partnerId"]
+      end
+
+      def set_user(data)
+        @user_id = data["userId"]
+        @user_auth_token = data["userAuthToken"]
+      end
+
+      def auth_token
+        @auth_token || @user_auth_token || @partner_auth_token
+      end
+
+      def sync_time
+        return nil unless @server_sync_time
+        (@server_sync_time + (Time.now.to_f - @start_time)).to_i
+      end
+
+      def call(method, **data)
+        start_request(method)
+
+        params = build_params(method)
+        url = build_url(method, params)
+        request_info = build_data(method, data)
+
+        result = make_http_request(url, request_info[:data], params, request_info[:encrypted])
+        parse_response(result)
+      end
+
+      def test_connectivity
+        return false unless @connection
+        
+        begin
+          test_url = "#{@api_tls ? 'https' : 'http'}://#{@api_host}:#{@api_tls ? 443 : 80}"
+          test_url(test_url)
+        rescue StandardError
+          false
+        end
+      end
+
+      def test_url(url)
+        response = @connection.head(url)
+        response.status == 200
+      rescue
+        false
+      end
+
+      private
+
+      def sync_time=(sync_time_encrypted)
+        @server_sync_time = @cryptor.decrypt_sync_time(sync_time_encrypted)
+      end
+
+      def build_connection(proxy)
+        options = {
+          headers: { 'User-Agent' => 'pianobar-2022.04.01' }
+        }
+        options[:proxy] = proxy if proxy
+
+        Faraday.new(options) do |f|
+          f.request :retry, max: 3, interval: 0.5, backoff_factor: 2
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      def start_request(method)
+        reset if REQUIRE_RESET.include?(method)
+        @start_time ||= Time.now.to_f
+      end
+
+      def encrypt(data, key = nil)
+        if key
+          # Use provided key to create temporary blowfish cryptor
+          temp_cryptor = BlowfishCryptor.new(key)
+          temp_cryptor.encrypt(data)
+        elsif @cryptor
+          # Use existing cryptor's underlying blowfish cryptor
+          @cryptor.instance_variable_get(:@bf_out).encrypt(data)
+        else
+          raise ArgumentError, "No encryption key or cryptor available"
+        end
+      end
+
+      def decrypt(data, key = nil)
+        if key
+          # Use provided key to create temporary blowfish cryptor
+          temp_cryptor = BlowfishCryptor.new(key)
+          temp_cryptor.decrypt(data)
+        elsif @cryptor
+          # Use existing cryptor's underlying blowfish cryptor
+          @cryptor.instance_variable_get(:@bf_in).decrypt(data)
+        else
+          raise ArgumentError, "No decryption key or cryptor available"
+        end
+      end
+
+      def build_url(method, params = {})
+        protocol = REQUIRE_TLS.include?(method) ? "https" : "http"
+        port = @api_tls ? 443 : 80
+        # Only include port if it's non-standard
+        port_string = (protocol == "https" && port == 443) || (protocol == "http" && port == 80) ? "" : ":#{port}"
+        base_url = "#{protocol}://#{@api_host}#{port_string}#{@api_path}"
+
+        # Build query string with parameters in specific order: method first, then others
+        query_parts = []
+        query_parts << "method=#{CGI.escape(method)}"
+        query_parts << "auth_token=#{CGI.escape(auth_token)}" if auth_token
+        query_parts << "user_auth_token=#{CGI.escape(@user_auth_token)}" if @user_auth_token
+        query_parts << "partner_id=#{CGI.escape(@partner_id.to_s)}" if @partner_id
+        query_parts << "user_id=#{CGI.escape(@user_id.to_s)}" if @user_id
+
+        query_string = query_parts.join('&')
+
+        "#{base_url}?#{query_string}"
+      end
+
+      def build_params(method)
+        remove_empty_values({
+          method: method,
+          auth_token: auth_token,
+          partner_id: @partner_id,
+          user_id: @user_id
+        })
+      end
+
+      def build_data(method, data)
+        data = data.dup
+        data[:userAuthToken] = @user_auth_token if @user_auth_token
+        data[:partnerAuthToken] = @partner_auth_token if @partner_auth_token && !@user_auth_token
+        data[:syncTime] = sync_time
+
+        json_data = JSON.generate(remove_empty_values(data))
+
+        if NO_ENCRYPT.include?(method) || !@cryptor
+          { data: json_data, encrypted: false }
+        else
+          { data: @cryptor.encrypt(json_data), encrypted: true }
+        end
+      end
+
+      def make_http_request(url, data, params, encrypted = false)
+        begin
+          response = @connection.post(url) do |req|
+            # Don't set req.params since URL already has query string
+            # Ensure body is properly encoded as UTF-8 string
+            req.body = data.to_s.force_encoding('UTF-8')
+            # Set Content-Type for JSON, but not for encrypted data
+            req.headers['Content-Type'] = 'application/json' unless encrypted
+            # Match pydora's headers
+            req.headers['Accept'] = '*/*'
+            req.headers['Connection'] = 'keep-alive'
+          end
+          
+          response.raise_error unless response.success?
+          response.body
+        rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+          # Let the retry middleware handle transient errors first
+          # If we get here, retries have been exhausted
+          raise NetworkError, "Network error: #{e.message}"
+        end
+      end
+
+      def parse_response(result)
+        parsed = JSON.parse(result)
+
+        if parsed["stat"] == "ok"
+          parsed["result"]
+        else
+          error_code = parsed["code"]
+          error_message = parsed["message"]
+          raise Pandoru.create_api_error(error_message, error_code)
+        end
+      rescue JSON::ParserError => e
+        raise NetworkError, "Invalid JSON response: #{e.message}"
+      end
+
+      def remove_empty_values(hash)
+        hash.reject { |_, v| v.nil? }
+      end
+    end
+  end
+end

data/lib/pandoru/version.rb

@@ -0,0 +1,3 @@
+module Pandoru
+  VERSION = "0.1.0"
+end