Add Transfer a User's Playback (#23)

* wip

* fixed devices

* added transfer_playback docs

* cleanup

* added model class

* added Spotify::SDK::Model

* bug fix

* migrated codebase to spotify::sdk::model

* fixed tests

* polished stub_spotify_api_request

* fixup

* fixup

* added tests

* sdk -> _sdk_opts

Author: bih

lib/spotify/sdk.rb

@@ -8,6 +8,7 @@
 require "spotify/sdk/initialization/query_string"
 require "spotify/sdk/initialization/url_string"
 require "spotify/sdk/base"
+require "spotify/sdk/model"
 require "spotify/sdk/connect"
 require "spotify/sdk/connect/device"
 

lib/spotify/sdk/base.rb

@@ -17,7 +17,7 @@ class Base
       #   @auth = Spotify::SDK::Base.new(@sdk)
       #
       #   @sdk = Spotify::SDK.new("access_token_here")
-      #   @sdk.to_hash # => { access_token: ..., expires_in: ... }
+      #   @sdk.to_hash # => { access_token: ..., expires_at: ... }
       #
       # @param [Spotify::SDK] sdk An instance of Spotify::SDK as a reference point.
       #
@@ -34,14 +34,22 @@ def initialize(sdk)
       # Handle HTTParty responses.
       #
       # @example
-      #   handle_response self.class.get("/v1/me/player/devices", @options)
+      #   # Return the Hash from the JSON response.
+      #   send_http_request(:get, "/v1/me/player/devices", @options)
       #
-      # @param [HTTParty::Response] response_obj The response object when a HTTParty request is made.
+      #   # Return the raw HTTParty::Response object.
+      #   send_http_request(:get, "/v1/me/player/devices", @options.merge(raw: true))
+      #
+      # @param [Hash,HTTParty::Response] response The response from the HTTP request.
       # @return
       #
-      def handle_response(response_obj, &_block)
-        response = block_given? ? yield : response_obj
-        response.parsed_response.deep_symbolize_keys
+      def send_http_request(method, endpoint, opts={}, &_block)
+        sdk_opts = opts[:_sdk_opts].presence || {}
+        opts_sdk = {raw: false, expect_nil: false}.merge(sdk_opts)
+        response = self.class.send(method, endpoint, @options.merge(opts))
+        response = response.parsed_response.try(:deep_symbolize_keys) if opts_sdk[:raw] == false
+        response = true if opts_sdk[:expect_nil] == true && response.nil?
+        response
       end
 
       attr_reader :sdk

lib/spotify/sdk/connect.rb

@@ -16,9 +16,9 @@ class Connect < Base
       # @return
       #
       def devices(override_opts={})
-        resp = self.class.get("/v1/me/player/devices", @options.merge(override_opts))
-        handle_response(resp)[:devices].map do |device|
-          Spotify::SDK::Connect::Device.new(device)
+        response = send_http_request(:get, "/v1/me/player/devices", override_opts)
+        response[:devices].map do |device|
+          Spotify::SDK::Connect::Device.new(device, self)
         end
       end
     end

lib/spotify/sdk/connect/device.rb

@@ -3,7 +3,52 @@
 module Spotify
   class SDK
     class Connect
-      class Device < OpenStruct
+      class Device < Model
+        ##
+        # Transfer a user's playback to another device, and continue playing.
+        # PUT /v1/me/player
+        #
+        # @example
+        #   device = @sdk.connect.transfer_playback!
+        #
+        # @see https://developer.spotify.com/web-api/transfer-a-users-playback/
+        #
+        # @return [Spotify::SDK::Connect::Device] self Return itself, so chained methods can be supported.
+        #
+        def transfer_playback!
+          transfer_playback_method(playing: true)
+          self
+        end
+
+        ##
+        # Transfer a user's playback to another device, and pause.
+        # PUT /v1/me/player
+        #
+        # @example
+        #   device = @sdk.connect.transfer_state!
+        #
+        # @see https://developer.spotify.com/web-api/transfer-a-users-playback/
+        #
+        # @return [Spotify::SDK::Connect::Device] self Return itself, so chained methods can be supported.
+        #
+        def transfer_state!
+          transfer_playback_method(playing: false)
+          self
+        end
+
+        private
+
+        def transfer_playback_method(playing:)
+          override_opts = {
+            _sdk_opts: {expect_nil: true},
+            body:      {
+              device_ids: [id],
+              play:       playing
+            }.to_json
+          }
+
+          parent.send_http_request(:put, "/v1/me/player", override_opts)
+        end
       end
     end
   end

lib/spotify/sdk/initialization.rb

@@ -52,9 +52,9 @@ def detect(subject)
           when 1
             matches.first.perform
           when 0
-            raise Spotify::Errors::InitializationObjectInvalidError
+            raise Spotify::Errors::InitializationObjectInvalidError.new
           else
-            raise Spotify::Errors::InitializationObjectDuplicationError
+            raise Spotify::Errors::InitializationObjectDuplicationError.new
           end
         end
       end
@@ -63,12 +63,12 @@ def detect(subject)
 
   class Errors
     ##
-    # A Error class for when the initialization subjectect is not valid (see `initialize(subject)` for more info).
+    # A Error class for when the initialization subject is not valid (see `initialize(subject)` for more info).
     #
     class InitializationObjectInvalidError < StandardError; end
 
     ##
-    # A Error class for when the initialization subjectect matches against multiple selectors.
+    # A Error class for when the initialization subject matches against multiple selectors.
     # When this Error occurs, this becomes an internal bug. It should be filed on the GitHub issue tracker.
     #
     class InitializationObjectDuplicationError < StandardError; end

lib/spotify/sdk/model.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Spotify
+  class SDK
+    ##
+    # For each SDK response object (i.e. Device), we have a Model class. We're using OpenStruct.
+    #
+    class Model < OpenStruct
+      ##
+      # Initialize a new Model instance.
+      #
+      # @param [Hash] hash The response payload.
+      # @param [Spotify::SDK] parent The SDK object for context.
+      #
+      def initialize(payload, parent)
+        @payload = payload
+        validate_payload
+
+        @parent = parent
+        validate_parent
+
+        super(payload)
+      end
+
+      ##
+      # A reference to Spotify::SDK::Connect, so we can also do stuff.
+      #
+      attr_reader :parent
+
+      private
+
+      def validate_payload
+        raise Spotify::Errors::ModelPayloadExpectedToBeHashError.new unless @payload.instance_of? Hash
+      end
+
+      def validate_parent
+        raise Spotify::Errors::ModelParentInvalidSDKBaseObjectError.new unless @parent.is_a? Spotify::SDK::Base
+      end
+    end
+  end
+
+  class Errors
+    ##
+    # A Error class for when the payload is not a Hash instance.
+    #
+    class ModelPayloadExpectedToBeHashError < StandardError; end
+
+    ##
+    # A Error class for when the parent is not a Spotify::SDK::Base instance.
+    #
+    class ModelParentInvalidSDKBaseObjectError < StandardError; end
+  end
+end

spec/lib/spotify/sdk/connect/device_spec.rb

@@ -13,14 +13,38 @@
       volume_percent: 100
     }
   end
-  subject { Spotify::SDK::Connect::Device.new(raw_data) }
+  let(:sdk) { Spotify::SDK.new("access_token") }
+  let(:connect_sdk) { Spotify::SDK::Connect.new(sdk) }
+  subject { Spotify::SDK::Connect::Device.new(raw_data, connect_sdk) }
 
-  describe "#raw_data" do
+  describe "#to_h" do
     it "returns the correct value" do
       expect(subject.to_h).to eq raw_data
     end
   end
 
+  describe "#transfer_playback!" do
+    it "should make an api call" do
+      stub = stub_request(:put, "https://api.spotify.com/v1/me/player")
+             .with(body:    {device_ids: [raw_data[:id]], play: true}.to_json,
+                   headers: {Authorization: "Bearer access_token"})
+
+      subject.transfer_playback!
+      expect(stub).to have_been_requested
+    end
+  end
+
+  describe "#transfer_state!" do
+    it "should make an api call" do
+      stub = stub_request(:put, "https://api.spotify.com/v1/me/player")
+             .with(body:    {device_ids: [raw_data[:id]], play: false}.to_json,
+                   headers: {Authorization: "Bearer access_token"})
+
+      subject.transfer_state!
+      expect(stub).to have_been_requested
+    end
+  end
+
   context "Method Missing" do
     it "connects method calls to raw_data" do
       raw_data.each do |key, value|

spec/lib/spotify/sdk/connect_spec.rb

@@ -6,9 +6,7 @@
   let(:connect_sdk) { Spotify::SDK.new("access_token").connect }
 
   describe "#devices" do
-    before(:each) do
-      stub_spotify_api_request(:get, "/v1/me/player/devices")
-    end
+    before(:each) { stub_spotify_api_request(:get, "/v1/me/player/devices") }
     let(:devices) { connect_sdk.devices }
 
     it "should return an list of devices" do
@@ -26,19 +24,4 @@
       expect(device.volume_percent).to eq 100
     end
   end
-
-  private
-
-  def stub_spotify_api_request(method, endpoint)
-    fixture_filename = "%s%s.json" % [method.to_s, endpoint.tr("/", "-")]
-    spec_path = File.expand_path("../../../../", __FILE__)
-    fixture_path = spec_path + "/support/fixtures/%s" % fixture_filename
-
-    request_headers = {Authorization: "Bearer access_token"}
-    response_headers = {"Content-Type": "application/json; charset=utf-8"}
-
-    stub_request(method, "https://api.spotify.com%s" % endpoint)
-      .with(headers: request_headers)
-      .to_return(status: 200, body: File.read(fixture_path), headers: response_headers)
-  end
 end

spec/lib/spotify/sdk/model_spec.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Spotify::SDK::Model do
+  let(:payload) { {id: 123_456, username: "example", country_code: "GB"} }
+  let(:sdk) { Spotify::SDK.new("access_token") }
+  let(:connect_sdk) { Spotify::SDK::Connect.new(sdk) }
+
+  context "good initialization" do
+    it "should not raise an error" do
+      expect {
+        Spotify::SDK::Model.new(payload, connect_sdk)
+      }.not_to raise_error
+    end
+  end
+
+  context "bad initialization" do
+    context "parameters count" do
+      it "should raise an error if zero parameters are given" do
+        expect {
+          Spotify::SDK::Model.new
+        }.to raise_error ArgumentError
+      end
+
+      it "should raise an error if only one parameter is given" do
+        expect {
+          Spotify::SDK::Model.new(payload)
+        }.to raise_error ArgumentError
+      end
+    end
+
+    context "first parameter" do
+      it "should raise an error if not a hash" do
+        expect {
+          Spotify::SDK::Model.new("Hi world", connect_sdk)
+        }.to raise_error Spotify::Errors::ModelPayloadExpectedToBeHashError
+      end
+    end
+
+    context "second parameter" do
+      it "should raise an error if not a hash" do
+        expect {
+          Spotify::SDK::Model.new(payload, "Hi world")
+        }.to raise_error Spotify::Errors::ModelParentInvalidSDKBaseObjectError
+      end
+    end
+  end
+end

spec/spec_helper.rb

@@ -5,17 +5,58 @@
 require "coveralls"
 require "webmock/rspec"
 
+# Code coverage.
 Coveralls.wear!
 
+# Capture all API calls.
 WebMock.disable_net_connect!(allow_localhost: true)
 
+module Helpers
+  ##
+  # Mock Spotify API requests.
+  #
+  def stub_spotify_api_request(method, endpoint)
+    StubSpotifyAPIRequestHelper.new(method, endpoint).perform
+  end
+
+  class StubSpotifyAPIRequestHelper < OpenStruct
+    REQUEST_HEADERS = {Authorization: "Bearer access_token"}.freeze
+    RESPONSE_HEADERS = {"Content-Type": "application/json; charset=utf-8"}.freeze
+
+    def initialize(method, endpoint)
+      @method   = method
+      @endpoint = endpoint
+    end
+
+    def perform
+      WebMock::API.stub_request(@method, "https://api.spotify.com%s" % @endpoint)
+                  .with(headers: REQUEST_HEADERS)
+                  .to_return(status: 200, body: File.read(fixture_path), headers: RESPONSE_HEADERS)
+    end
+
+    private
+
+    def fixture_filename
+      "%s%s.json" % [@method.to_s, @endpoint.tr("/", "-")]
+    end
+
+    def fixture_path
+      File.expand_path("../", __FILE__) + "/support/fixtures/%s" % fixture_filename
+    end
+  end
+end
+
 RSpec.configure do |config|
   # Enable flags like --only-failures and --next-failure
   config.example_status_persistence_file_path = ".rspec_status"
 
   # Disable RSpec exposing methods globally on `Module` and `main`
   config.disable_monkey_patching!
 
+  # Include custom helper methods.
+  config.include Helpers
+
+  # Use expect syntax.
   config.expect_with :rspec do |c|
     c.syntax = :expect
   end