googol 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6945690068a1360419e43033caf75ed53ee0d231
-  data.tar.gz: 20ad10bdfe492d8bdbbc356c5c2b4d5758b83c07
+  metadata.gz: 4cced40105e7959c839fa4349625b98fddb0857b
+  data.tar.gz: ba65e22653877a3cf0aadc9d4ef81838ea09879e
 SHA512:
-  metadata.gz: 4e674a9f13fa33db3184969ba36b02df88230165fdef7a67679a2622d6a8fc2dd919edd28f16c2fc7f9cef6f0a8f06d7cb56db58828d6a3020c26cb0292ab241
-  data.tar.gz: 4e73ed288bb6b2fe9ea416cbad761c82fac7e58816b18b3257bc4c18d153390276612606fc886c54f395be40b0a193784580cdbfd23376be95b6e056f74856af
+  metadata.gz: 69a0f394c1059aec6a06159f5e042aa7ec1f539a9646c0bbd06ae9b3e2362ffc9f115c10ad1887dcea477b993e069a7c21e007ee29605c0ca760d35f3962652f
+  data.tar.gz: 2be89f5a97ce5285ed09bf0fcb900879c437f656a8232c495b9ddfc9b073b80adb03630d375fb2f6d4509d1d5b9580cd647f325b1de3df9e210c3fd87ab4a8fd

data/README.md

@@ -31,8 +31,27 @@ account.email #=> 'user@google.com'
 
 ```ruby
 account = Googol::YoutubeAccount.new auth_params
-account.perform! :like, :video, 'Kd5M17e7Wek' # => adds 'Tongue' to your 'Liked videos'
-account.perform! :subscribe_to, :channel, 'UC7eaRqtonpyiYw0Pns0Au_g' # => subscribes to R.E.M.’s channel
+account.like! video_id: 'Kd5M17e7Wek' # => adds 'Tongue' to your 'Liked videos'
+account.subscribe_to! channel_id: 'UC7eaRqtonpyiYw0Pns0Au_g' # => subscribes to R.E.M.’s channel
+playlist_id = account.find_or_create_playlist_by title: 'Favorite Music Videos'
+account.add_to! playlist_id: playlist_id, video_id: 'Kd5M17e7Wek' # => adds 'Tongue' to your 'Favorite Music Videos' playlist
+
+# Adds a video to a playlist as a Youtube account
+#
+# @param [Hash] target The target of the 'add_to' activity
+# @option target [String] :video_id The ID of the video to add
+# @option target [String] :playlist_id The ID of the playlist to add to
+#
+# @see https://developers.google.com/youtube/v3/docs/playlistItems/insert
+#
+def add_to!(target = {})
+  video_id, playlist_id = fetch! target, :video_id, :playlist_id
+  resource = {videoId: video_id, kind: 'youtube#video'}
+  youtube_request! path: '/playlistItems?part=snippet', json: true,
+    method: :post, snippet: {playlistId: playlist_id, resourceId: resource}
+end
+
+
 ```
 
 The full documentation is available at [rubydoc.info](http://rubydoc.info/github/fullscreeninc/googol/master/frames).
@@ -60,10 +79,8 @@ Youtube accounts
 Use `Googol::YoutubeAccount` to send and retrieve data to Youtube,
 impersonating an existing Youtube account.
 
-Available instance methods are `id`, `title`, `description`, and `thumbnail_url`.
-
-Additionally, the `perform!` method lets you executes promotional actions as
-a Youtube account, such as liking a video or subscribing to a channel.
+Available instance methods are `id`, `title`, `description`, `thumbnail_url`,
+`like!`, `subscribe_to!`, `find_or_create_playlist_by`, and `add_to!`.
 
 These methods require user authentication (see below).
 
@@ -139,7 +156,7 @@ To install on your system, run
 
 To use inside a bundled Ruby project, add this line to the Gemfile:
 
-    gem 'googol', '~> 0.1.0'
+    gem 'googol', '~> 0.2.0'
 
 Since the gem follows [Semantic Versioning](http://semver.org),
 indicating the full version in your Gemfile (~> *major*.*minor*.*patch*)

data/lib/googol/authenticable.rb

@@ -33,10 +33,8 @@ module Googol
     #   * ...
     def credentials
       @credentials ||= request! method: :post,
-        host: 'https://accounts.google.com',
-        path: '/o/oauth2/token',
-        body: credentials_params,
-        valid_if: -> response, body {response.code == '200'}
+        host: 'https://accounts.google.com', path: '/o/oauth2/token',
+        body: credentials_params
     end
 
   private

data/lib/googol/google_account.rb

@@ -35,11 +35,8 @@ module Googol
     #   * :locale [String] The account’s preferred locale.
     #   * :hd [String] The hosted domain name for the accounts’s Google Apps.
     def info
-      @info ||= request! method: :get,
-        auth: credentials[:access_token],
-        host: 'https://www.googleapis.com',
-        path: '/oauth2/v2/userinfo',
-        valid_if: -> response, body {response.code == '200'}
+      @info ||= request! auth: credentials[:access_token],
+        host: 'https://www.googleapis.com', path: '/oauth2/v2/userinfo'
     end
 
     # Define a method to return each attribute of the profile separately.

data/lib/googol/readable.rb

@@ -17,9 +17,17 @@ module Googol
       info[:snippet][:description]
     end
 
-    # Return the URL of the Youtube object thumbnail
-    def thumbnail_url
-      info[:snippet][:thumbnails][:default][:url]
+    # Return the URL of the thumbnail image of the Youtube channel/videp.
+    #
+    # @option size [Symbol] :default The size of the thumbnail. Valid values are:
+    #                       :default (channel: 88px x 88px, video: 120px x 90px)
+    #                       :medium (channel: 240px x 240px, video: 320px x 180px)
+    #                       :high (channel: 800px x 800px, video: 480px x 360px)
+    #
+    # @return [String] The thumbnail URL
+    def thumbnail_url(size = :default)
+      size = :default unless [:medium, :high].include? size
+      info[:snippet][:thumbnails][size][:url]
     end
 
     # Return the kind of the Youtube object (either 'channel' or 'video')

data/lib/googol/requestable.rb

@@ -19,13 +19,13 @@ module Googol
       http = Net::HTTP.new url.host, url.port
       http.use_ssl = true
       request = case params[:method]
-        when :get then Net::HTTP::Get.new params[:path]
         when :post then
           if params[:json]
             Net::HTTP::Post.new params[:path], initheader = {'Content-Type' =>'application/json'}
           else
             Net::HTTP::Post.new params[:path]
           end
+        else Net::HTTP::Get.new params[:path]
       end
       if params[:json]
         request.body = params[:body].to_json
@@ -34,12 +34,12 @@ module Googol
       end if params[:body]
 
       request['Authorization'] = 'Bearer ' + params[:auth] if params[:auth]
+
       response = http.request(request)
 
       body = JSON.parse response.body if response.body
 
-      if params[:valid_if] ? params[:valid_if].call(response, body) : true
-        body = params[:extract].call body if params[:extract]
+      if response.code == params.fetch(:code, 200).to_s
         body ? deep_symbolize_keys(body) : true
       else
         raise RequestError, body
@@ -49,10 +49,18 @@ module Googol
   private
 
     def deep_symbolize_keys(hash)
+      def symbolize(value)
+        case value
+          when Hash then deep_symbolize_keys value
+          when Array then value.map{|item| symbolize item}
+          else value
+        end
+      end
+
       {}.tap do |result|
         hash.each do |k, v|
           key = k.to_sym rescue k
-          result[key] = v.is_a?(Hash) ? deep_symbolize_keys(v) : v
+          result[key] = symbolize v
         end
       end
     end

data/lib/googol/version.rb

@@ -1,3 +1,3 @@
 module Googol
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

data/lib/googol/youtube_account.rb

@@ -14,7 +14,7 @@ module Googol
   #   * Use the authorization code to initialize the YoutubeAccount and like the video:
   #
   #       account = Googol::YoutubeAccount.new code: code, redirect_url: redirect_url
-  #       account.perform! :like, :video, 'Kd5M17e7Wek' # => likes the video
+  #       account.like! video_id: 'Kd5M17e7Wek' # => likes the video
   #
   class YoutubeAccount
     include Authenticable
@@ -36,35 +36,156 @@ module Googol
     #       + :medium [Hash] Medium thumbnail URL (88px x 88px)
     #       + :high [Hash] High thumbnail URL (88px x 88px)
     def info
-      @info ||= request! method: :get,
-        auth: credentials[:access_token],
-        host: 'https://www.googleapis.com',
-        path: '/youtube/v3/channels?part=id,snippet&mine=true',
-        valid_if: -> resp, body {resp.code == '200' && body['items'].any?},
-        extract: -> body {body['items'].first}
+      @info_response ||= youtube_request! path: '/channels?part=id,snippet&mine=true'
+      @info_response[:items].first
     end
 
-    ## Promote a Youtube target resource on this Youtube Channel
-    # Note that liking a video does not also subscribe to a channel
-    def perform!(activity, target_kind, target_id)
-      params = {}.tap do |params|
-        params[:method] = :post
-        params[:auth] = credentials[:access_token]
-        params[:host] = 'https://www.googleapis.com'
+    # Like a video as a Youtube account
+    #
+    # @param [Hash] target The target of the 'like' activity
+    # @option target [String] :video_id The ID of the video to like
+    #
+    # @see https://developers.google.com/youtube/v3/docs/videos/rate
+    #
+    # @note Liking a video does not also subscribe to its channel
+    #
+    def like!(target = {})
+      video_id = fetch! target, :video_id
+      path = "/videos/rate?rating=like&id=#{video_id}"
+      youtube_request! path: path, method: :post, code: 204
+    end
+
+    # Subscribe a Youtube account to a channel
+    #
+    # @param [Hash] target The target of the 'subscribe' activity
+    # @option target [String] :channel_id The ID of the channel to subscribe to
+    #
+    # @see https://developers.google.com/youtube/v3/docs/subscriptions/insert
+    #
+    def subscribe_to!(target = {})
+      channel_id = fetch! target, :channel_id
+      youtube_request! path: '/subscriptions?part=snippet', json: true,
+        method: :post, body: {snippet: {resourceId: {channelId: channel_id}}}
+    end
+
+    # Return the first playlist of the Youtube account matching the attributes.
+    # If such a playlist is not found, it gets created and yielded to the block.
+    #
+    # @note Inspired by Ruby on Rails’ find_or_create_by
+    #
+    # @param [Hash] target The target of the 'add_to' activity
+    # @option target [String] :video_id The ID of the video to add
+    # @option target [String] :playlist_id The ID of the playlist to add to
+    #
+    # @see https://developers.google.com/youtube/v3/docs/playlistItems/insert
+    #
+    def find_or_create_playlist_by(attributes = {}, &block)
+      find_playlist_by(attributes) || create_playlist!(attributes, &block)
+    end
+
+    # Adds a video to a playlist as a Youtube account
+    #
+    # @param [Hash] target The target of the 'add_to' activity
+    # @option target [String] :video_id The ID of the video to add
+    # @option target [String] :playlist_id The ID of the playlist to add to
+    #
+    # @see https://developers.google.com/youtube/v3/docs/playlistItems/insert
+    #
+    def add_to!(target = {})
+      video_id, playlist_id = fetch! target, :video_id, :playlist_id
+      resource = {videoId: video_id, kind: 'youtube#video'}
+      youtube_request! method: :post, json: true,
+        path: '/playlistItems?part=snippet',
+        body: {snippet: {playlistId: playlist_id, resourceId: resource}}
+    end
 
-        case [activity.to_sym, target_kind.to_sym]
-        when [:like, :video]
-          params[:path] = "/youtube/v3/videos/rate?rating=like&id=#{target_id}"
-          params[:valid_if] = -> response, body {response.code == '204'}
-        when [:subscribe_to, :channel]
-          params[:json] = true
-          params[:path] = '/youtube/v3/subscriptions?part=snippet'
-          params[:body] = {snippet: {resourceId: {channelId: target_id}}}
-          params[:valid_if] = -> response, body {response.code == '200'}
-        else
-          raise RequestError, "#{activity} invalid for #{target_kind} #{target_id}"
-        end
+  private
+
+    # Creates a playlist for a Youtube account and yield it to the block
+    #
+    # @param [Hash] attributes The attributes of the new playlist
+    # @option attributes [String] :title Title of the playlist
+    # @option attributes [String] :description Description of the playlist
+    #
+    # @return [String] The ID of the playlist
+    #
+    # @see https://developers.google.com/youtube/v3/docs/playlists/insert
+    #
+    def create_playlist!(attrs = {}, &block)
+      snippet = {title: attrs[:title], description: attrs[:description]}
+      playlist = youtube_request! json: true, method: :post,
+        path: '/playlists?part=snippet,status',
+        body: {snippet: snippet, status: {privacyStatus: :public}}
+      yield playlist if block_given?
+      playlist[:id]
+    end
+
+    # Return the first playlist of the Youtube account matching the attributes.
+    #
+    # @param [Hash] filters The filter to query the list of playlists with.
+    # @option title [String or Regex] Filter on the title
+    # @option description [String or Regex] Filter on the description
+    #
+    # @example account.find_playlist_by title: 'Title' # => 'e45fXDsdsdsd'
+    # @example account.find_playlist_by description: 'xxxx' # => nil
+    #
+    # @note Google API does not have a "search" endpoint, therefore we have
+    # to scan the list of playlist page by page, limiting at 10 pages to
+    # prevent this function from running forever (50 playlists per page).
+    #
+    # @return [String or nil] The ID of the playlist (or nil if not found)
+    def find_playlist_by(filters = {})
+      page = filters.delete(:page) || 1
+
+      path = "/playlists?part=id,snippet&mine=true"
+      path << "&maxResults=#{filters.delete(:max) || 50 }"
+      path << "&pageToken=#{filters.delete :token}" if filters[:token]
+
+      response = youtube_request! path: path
+
+      if playlist = response[:items].find{|p| playlist_matches? p, filters}
+        playlist[:id]
+      elsif page < 10 && token = response[:nextPageToken]
+        find_playlist_by filters.merge page: page, token: token
       end
+    end
+
+    # Checks if the playlist matches the given filters.
+    #
+    # @param [Hash] filters The filter to query the list of playlists with.
+    # @option title [String or Regex] Filter on the title
+    # @option description [String or Regex] Filter on the description
+    #
+    # @note String filters match when they are included in the specified field
+    #       Regex filters match when they match as a Regex against the field
+    #
+    # @example Given a playlist x with title: 'A title', description: 'Example'
+    #     playlist_matches? x, title: 'tit' # => true
+    #     playlist_matches? x, title: 'TIT' # => false
+    #     playlist_matches? x, title: /^TIT/i # => true
+    #     playlist_matches? x, title: /^TIT/i, description: 'Ex' # => true
+    #     playlist_matches? x, title: /^TIT/i, description: 'xxx' # => false
+    #
+    # @return [Boolean] Whether the playlist matches the filters
+    def playlist_matches?(playlist, filters = {})
+      filters.all? do |attribute, string_or_regex|
+        playlist[:snippet].fetch(attribute, '')[string_or_regex]
+      end
+    end
+
+    # Fetch keys from a hash, raising a custom exception when not found
+    def fetch!(hash, *keys)
+      values = keys.map do |key|
+        hash.fetch(key) {raise RequestError, "Missing #{key} in #{hash}"}
+      end
+      keys.one? ? values.first : values
+    end
+
+    # Overrides the super.request! with Youtube-specific params
+    def youtube_request!(params = {})
+      params[:path] = "/youtube/v3#{params[:path]}"
+      params[:auth] = credentials[:access_token]
+      params[:host] = 'https://www.googleapis.com'
       request! params
     end
 

data/lib/googol/youtube_resource.rb

@@ -42,15 +42,16 @@ module Googol
     #     - :description [String] The channel's description.
     #     - :publishedAt [String] The date and time that the channel was created. The value is specified in ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) format.
     #     - :thumbnails [Hash]
-    #       + :default [Hash] Default thumbnail URL (88px x 88px)
-    #       + :medium [Hash] Medium thumbnail URL (88px x 88px)
-    #       + :high [Hash] High thumbnail URL (88px x 88px)
+    #       + :default [Hash] Default thumbnail URL (channel: 88px x 88px, video: 120px x 90px)
+    #       + :medium [Hash] Medium thumbnail URL (channel: 240px x 240px, video: 320px x 180px)
+    #       + :high [Hash] High thumbnail URL (channel: 800px x 800px, video: 480px x 360px)
     def info
-      @info ||= request! method: :get,
-        host: 'https://www.googleapis.com',
-        path: "/youtube/v3/#{info_path}",
-        valid_if: -> resp, body {resp.code == '200' && body['items'].any?},
-        extract: -> body {body['items'].first}
+      @info_response ||= request! host: 'https://www.googleapis.com', path: "/youtube/v3/#{info_path}"
+      if @info_response[:items].any?
+        @info_response[:items].first
+      else
+        raise RequestError, "Youtube resource not found at #{@url}"
+      end
     end
 
   private

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: googol
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-09 00:00:00.000000000 Z
+date: 2014-04-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler