pandoru 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2e2bd7b5d026ed3c16ee35173ca22f10839f4f486acd3259c8f5ed43c9b96053
+  data.tar.gz: 25ce0f4f8a3d6bcbf78dadf9a4eb7fa20ae3a0e77bb68e979ffd9a3acc1e2f91
+SHA512:
+  metadata.gz: 8561e8704472f4c3bbec08198a85d84bca87687fa43bad8a08239f49228e7890aaaff55b0d66bd591420b22639de25c40a1aa421124743452b1939601d900b09
+  data.tar.gz: cd0f0849b4a1128801be0debc5613933d4757dad32327cf5b914a093e8501e3be84596bb12a58b75db29dd4b970ae6d0a29ab730d4cf28d721522bf71188ddfd

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based
+on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-25
+
+Initial public release. A Ruby port of pydora (tracking upstream `pydora 2.3.1`)
+targeting Pandora's partner/device JSON API (`tuner.pandora.com/services/json/`).
+
+### Added
+- `Station` model now parses extended attributes: music seeds
+  (`seed_artists`, `seed_songs`, `seed_genres`) and feedback
+  (`thumbs_up`, `thumbs_down`) via new `StationSeed`/`StationSeeds`,
+  `SongFeedback`/`StationFeedback` sub-models.
+- `TrackExplanation` model for `track.explainTrack`, exposing `focus_traits`
+  (the Music-Genome-derived trait tags) with the trailing filler entry
+  stripped. `APIClient#explain_track` now returns this model.
+- `base64` declared as an explicit runtime dependency (removed from Ruby's
+  default gems in 3.4).
+
+### Fixed
+- Partner authentication: the default partner **username** is now `android`
+  (the canonical partner) rather than `android-generic` (which is the
+  *device model*). The previous value caused `partnerLogin` to fail with
+  INVALID_PARTNER_LOGIN.
+- Corrected the encryption/decryption key orientation in the bundled default
+  partner settings.

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Dale Stevens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,263 @@
+# Pandoru
+
+**Pandoru** is a Ruby port of the Python `pydora` library, providing a comprehensive client for the unofficial Pandora music streaming API. This gem allows you to interact with Pandora programmatically to manage stations, get playlists, search for music, and control playback.
+
+> **Note**: This is an unofficial API client. Use at your own risk and respect Pandora's terms of service.
+
+---
+
+## Features
+
+- **Station Management**: Get station lists, create/delete stations, rename stations
+- **Playlist Access**: Retrieve playlists with track metadata and audio URLs  
+- **Music Search**: Search for songs, artists, and albums
+- **User Interaction**: Thumbs up/down, bookmarks, sleep songs
+- **Feedback Management**: Add/remove track feedback
+- **Station Seeds & Genome Traits**: Inspect a station's seed artists/songs/genres and a track's Music-Genome focus traits (`explain_track`)
+- **Genre Exploration**: Browse and create stations from genre seeds
+- **Multiple Audio Qualities**: Support for low, medium, and high quality audio streams
+- **Ruby Idioms**: Built with Ruby best practices and idiomatic patterns
+
+---
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pandoru'
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install pandoru
+```
+
+---
+
+## Usage
+
+### Configuration
+
+Pandoru requires Pandora partner credentials to function. You can configure these in several ways:
+
+#### 1. Using a Configuration Hash
+
+```ruby
+require 'pandoru'
+
+# Note: These are example credentials - you need real ones
+settings = {
+  "PARTNER_USER" => "your-partner-user",
+  "PARTNER_PASSWORD" => "your-partner-password", 
+  "DEVICE" => "your-device-type",
+  "DECRYPTION_KEY" => "your-decryption-key",
+  "ENCRYPTION_KEY" => "your-encryption-key"
+}
+
+client = Pandoru::ClientBuilder.from_settings_hash(settings)
+client.login("your_email@example.com", "your_password")
+```
+
+#### 2. Using Configuration Files
+
+Pandoru supports both pydora-style and pianobar-style configuration files:
+
+```ruby
+# From a pydora config file
+client = Pandoru::ClientBuilder.from_config_file("~/.pydora.cfg")
+
+# From a pianobar config file  
+client = Pandoru::ClientBuilder.from_config_file("~/.config/pianobar/config")
+```
+
+### Basic Operations
+
+#### Managing Stations
+
+```ruby
+# Get all user stations
+stations = client.get_station_list
+
+# Create a new station from search results
+search_results = client.search("Radiohead")
+station = client.create_station(search_token: search_results.first.music_token)
+
+# Rename a station
+client.rename_station(station.token, "My Radiohead Station")
+
+# Delete a station
+client.delete_station(station.token)
+```
+
+#### Working with Playlists
+
+```ruby
+# Get a playlist from a station
+playlist = client.get_playlist(station.token)
+
+playlist.each do |track|
+  puts "#{track.artist_name} - #{track.song_name}"
+  puts "Audio URL: #{track.audio_url}"
+  
+  # Rate the track
+  track.thumbs_up if track.allow_feedback
+  
+  # Bookmark the song or artist
+  track.bookmark_song
+  track.bookmark_artist
+end
+```
+
+#### Searching for Music
+
+```ruby
+# Search for music
+results = client.search("The Beatles", include_near_matches: true)
+
+results.songs.each do |song|
+  puts "Song: #{song.song_name} by #{song.artist_name}"
+end
+
+results.artists.each do |artist|
+  puts "Artist: #{artist.artist_name}"
+end
+```
+
+#### Managing Bookmarks
+
+```ruby
+# Get user bookmarks
+bookmarks = client.get_bookmarks
+
+bookmarks.song_bookmarks.each do |bookmark|
+  puts "Bookmarked song: #{bookmark.song_name} by #{bookmark.artist_name}"
+end
+
+bookmarks.artist_bookmarks.each do |bookmark|
+  puts "Bookmarked artist: #{bookmark.artist_name}"
+end
+```
+
+### Advanced Features
+
+#### Genre Stations
+
+```ruby
+# Browse genre stations
+genre_stations = client.get_genre_stations
+
+genre_stations.categories.each do |category|
+  puts "Category: #{category}"
+  genre_stations.stations_for_category(category).each do |station|
+    puts "  Station: #{station.name}"
+  end
+end
+```
+
+#### Audio Quality
+
+```ruby
+# Set default audio quality when creating client
+client = Pandoru::ClientBuilder.from_settings_hash(settings.merge(
+  "AUDIO_QUALITY" => "highQuality"  # or "mediumQuality", "lowQuality"
+))
+
+# Get specific quality audio URL for a track
+track = playlist.first
+high_quality_url = track.audio_url("highQuality")
+medium_quality_url = track.audio_url("mediumQuality")  
+low_quality_url = track.audio_url("lowQuality")
+```
+
+#### Error Handling
+
+```ruby
+begin
+  client.login("user@example.com", "password")
+rescue Pandoru::Errors::InvalidUserLogin
+  puts "Invalid username or password"
+rescue Pandoru::Errors::PandoraException => e
+  puts "Pandora API error: #{e.message} (Code: #{e.code})"
+end
+```
+
+---
+
+## API Reference
+
+### Client Classes
+
+- `Pandoru::Client::APIClient` - High-level API client with all Pandora operations
+- `Pandoru::Client::BaseAPIClient` - Lower-level client for advanced usage
+
+### Models
+
+- `Pandoru::Models::Station` - Represents a Pandora station
+- `Pandoru::Models::StationList` - Collection of user stations  
+- `Pandoru::Models::Playlist` - Collection of playlist items
+- `Pandoru::Models::PlaylistItem` - Individual track in a playlist
+- `Pandoru::Models::SearchResult` - Search results container
+- `Pandoru::Models::BookmarkList` - User's bookmarked songs and artists
+
+### Client Builders
+
+- `Pandoru::ClientBuilder.from_settings_hash(hash)` - Create client from settings hash
+- `Pandoru::ClientBuilder.from_config_file(path)` - Create client from config file
+- `Pandoru::ClientBuilder.default_client()` - Create client with default settings
+
+---
+
+## Architecture
+
+Pandoru is architected similarly to the original pydora library:
+
+- **Transport Layer**: Handles HTTP communication and encryption/decryption
+- **Client Layer**: Provides high-level API methods
+- **Models Layer**: Represents Pandora data structures with Ruby idioms
+- **Builders Layer**: Factory classes for creating configured clients
+
+The Ruby port maintains compatibility with pydora's API while providing Ruby-style interfaces and error handling.
+
+---
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+---
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/TwilightCoders/pandoru.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+---
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+---
+
+## Acknowledgments
+
+This Ruby gem is a port of the excellent [pydora](https://github.com/mcrute/pydora) Python library by Mike Crute and contributors. All credit for the original API reverse engineering and design goes to the pydora project.
+
+## Disclaimer
+
+This project is not affiliated with or endorsed by Pandora Media, Inc. Use of this library may violate Pandora's Terms of Service. Use at your own risk.

data/lib/pandoru/client.rb

@@ -0,0 +1,298 @@
+# Pandora API Client
+#
+# This module contains the top level API client that is responsible for calling
+# the API and returning the results in model format. There is a base API client
+# that is useful for lower level programming such as calling methods that aren't
+# directly supported by the higher level API client.
+#
+# The high level API client is what most clients should use and provides API
+# calls that map directly to the Pandora API and return model objects with
+# mappings from the raw JSON structures to Ruby objects.
+#
+# For simplicity use a client builder from Pandoru::ClientBuilder to create an
+# instance of a client.
+
+module Pandoru
+  module Client
+    # Base Pandora API Client
+    # The base API client has lower level methods that are composed together to
+    # provide higher level functionality.
+    class BaseAPIClient
+      LOW_AUDIO_QUALITY = "lowQuality"
+      MED_AUDIO_QUALITY = "mediumQuality"
+      HIGH_AUDIO_QUALITY = "highQuality"
+
+      ALL_QUALITIES = [LOW_AUDIO_QUALITY, MED_AUDIO_QUALITY, HIGH_AUDIO_QUALITY].freeze
+
+      attr_reader :transport, :partner_user, :partner_password, :device, :default_audio_quality
+      attr_accessor :username, :password
+
+      def initialize(transport, partner_user = nil, partner_password = nil, device = nil, default_audio_quality: MED_AUDIO_QUALITY)
+        @transport = transport
+        @partner_user = partner_user
+        @partner_password = partner_password
+        @device = device
+        @default_audio_quality = default_audio_quality
+        @username = nil
+        @password = nil
+      end
+
+      def login(username, password)
+        @username = username
+        @password = password
+        authenticate
+      end
+
+      def call(method, **kwargs)
+        begin
+          @transport.call(method, **kwargs)
+        rescue Errors::InvalidAuthToken
+          authenticate
+          @transport.call(method, **kwargs)
+        end
+      end
+
+      def self.get_qualities(start_at, return_all_if_invalid: true)
+        begin
+          idx = ALL_QUALITIES.index(start_at)
+          ALL_QUALITIES[0..idx]
+        rescue ArgumentError
+          return_all_if_invalid ? ALL_QUALITIES.dup : []
+        end
+      end
+
+      private
+
+      def partner_login
+        partner = @transport.call(
+          "auth.partnerLogin",
+          username: @partner_user,
+          password: @partner_password,
+          deviceModel: @device,
+          version: (@transport.class.const_defined?(:API_VERSION) ? @transport.class::API_VERSION : "5")
+        )
+
+        @transport.set_partner(partner)
+        partner
+      end
+
+      def authenticate
+        partner_login
+
+        user = @transport.call(
+          "auth.userLogin",
+          loginType: "user",
+          username: @username,
+          password: @password,
+          includePandoraOneInfo: true,
+          includeSubscriptionExpiration: true,
+          returnCapped: true,
+          includeAdAttributes: true,
+          includeAdvertiserAttributes: true,
+          xplatformAdCapable: true
+        )
+
+        @transport.set_user(user)
+        user
+      rescue Errors::InvalidPartnerLogin => e
+        raise Errors::InvalidUserLogin.new(e.message)
+      end
+    end
+
+    # High Level Pandora API Client
+    # The high level API client implements the entire functional API for Pandora.
+    # This is what clients should actually use.
+    class APIClient < BaseAPIClient
+      def get_station_list
+        data = call("user.getStationList", includeStationArtUrl: true)
+        Models::StationList.from_json(self, data)
+      end
+
+      def get_station_list_checksum
+        data = call("user.getStationListChecksum")
+        data["checksum"]
+      end
+
+      def get_playlist(station_token, additional_urls: nil)
+        params = { 
+          stationToken: station_token,
+          includeTrackLength: true,
+          xplatformAdCapable: true,
+          audioAdPodCapable: true
+        }
+        
+        if additional_urls
+          urls = additional_urls.map { |url| url.respond_to?(:value) ? url.value : url }
+          params[:additionalAudioUrl] = urls.join(",")
+        end
+        
+        data = call("station.getPlaylist", **params)
+        
+        # Add additional URLs parameter to each item for ad processing
+        if additional_urls
+          data["items"]&.each { |item| item["_paramAdditionalUrls"] = additional_urls }
+        end
+        
+        playlist = Models::Playlist.from_json(self, data)
+        
+        # Process ad items
+        playlist.each_with_index do |track, i|
+          if track.is_ad?
+            ad_track = get_ad_item(station_token, track.ad_token)
+            playlist[i] = ad_track
+          end
+        end
+        
+        playlist
+      end
+
+      def get_bookmarks
+        data = call("user.getBookmarks")
+        Models::BookmarkList.from_json(self, data)
+      end
+
+      def get_station(station_token)
+        data = call("station.getStation", 
+                   stationToken: station_token,
+                   includeExtendedAttributes: true)
+        Models::Station.from_json(self, data)
+      end
+
+      def add_artist_bookmark(track_token)
+        call("bookmark.addArtistBookmark", trackToken: track_token)
+      end
+
+      def add_song_bookmark(track_token)
+        call("bookmark.addSongBookmark", trackToken: track_token)
+      end
+
+      def delete_song_bookmark(bookmark_token)
+        call("bookmark.deleteSongBookmark", bookmarkToken: bookmark_token)
+      end
+
+      def delete_artist_bookmark(bookmark_token)
+        call("bookmark.deleteArtistBookmark", bookmarkToken: bookmark_token)
+      end
+
+      def search(search_text, include_near_matches: false, include_genre_stations: false)
+        data = call("music.search",
+                   searchText: search_text,
+                   includeNearMatches: include_near_matches,
+                   includeGenreStations: include_genre_stations)
+        Models::SearchResult.from_json(self, data)
+      end
+
+      def add_feedback(track_token, positive)
+        call("station.addFeedback",
+             trackToken: track_token,
+             isPositive: positive)
+      end
+
+      def add_music(music_token, station_token)
+        call("station.addMusic",
+             musicToken: music_token,
+             stationToken: station_token)
+      end
+
+      def create_station(search_token: nil, artist_token: nil, track_token: nil, song_token: nil)
+        params = {}
+        
+        if search_token
+          params[:musicToken] = search_token
+        elsif artist_token
+          params[:musicToken] = artist_token
+        elsif track_token
+          params[:musicToken] = track_token  
+        elsif song_token
+          params[:musicToken] = song_token
+        else
+          raise ArgumentError, "Must provide one of: search_token, artist_token, track_token, song_token"
+        end
+
+        data = call("station.createStation", **params)
+        Models::Station.from_json(self, data)
+      end
+
+      def delete_feedback(feedback_id)
+        call("station.deleteFeedback", feedbackId: feedback_id)
+      end
+
+      def delete_music(seed_id)
+        call("station.deleteMusic", seedId: seed_id)
+      end
+
+      def delete_station(station_token)
+        call("station.deleteStation", stationToken: station_token)
+      end
+
+      def get_genre_stations
+        data = call("station.getGenreStations")
+        Models::GenreStationList.from_json(self, data)
+      end
+
+      def get_genre_stations_checksum
+        data = call("station.getGenreStationsChecksum")
+        data["checksum"]
+      end
+
+      def rename_station(station_token, name)
+        call("station.renameStation",
+             stationToken: station_token,
+             stationName: name)
+      end
+
+      def explain_track(track_token)
+        data = call("track.explainTrack", trackToken: track_token)
+        Models::TrackExplanation.from_json(self, data)
+      end
+
+      def set_quick_mix(*station_ids)
+        call("user.setQuickMix", quickMixStationIds: station_ids.flatten)
+      end
+
+      def sleep_song(track_token)
+        call("user.sleepSong", trackToken: track_token)
+      end
+
+      def share_station(station_id, station_token, *emails)
+        call("station.shareStation",
+             stationId: station_id,
+             stationToken: station_token,
+             emails: emails.flatten)
+      end
+
+      def transform_shared_station(station_token)
+        call("station.transformSharedStation", stationToken: station_token)
+      end
+
+      def share_music(music_token, *emails)
+        call("music.shareMusic",
+             musicToken: music_token,
+             emails: emails.flatten)
+      end
+
+      def get_ad_item(station_id, ad_token)
+        raise Errors::ParameterMissing, "station_id must be defined, got: '#{station_id}'" if station_id.nil? || station_id.empty?
+        
+        ad_data = get_ad_metadata(ad_token)
+        ad_item = Models::AdItem.from_json(self, ad_data)
+        ad_item.station_id = station_id
+        ad_item.ad_token = ad_token
+        ad_item
+      end
+
+      def get_ad_metadata(ad_token)
+        call("ad.getAdMetadata",
+             adToken: ad_token,
+             returnAdTrackingTokens: true,
+             supportAudioAds: true)
+      end
+
+      def register_ad(station_id, tokens)
+        call("ad.registerAd",
+             stationId: station_id,
+             adTrackingTokens: tokens)
+      end
+    end
+  end
+end