googol 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 020552842d5bed2faefa55f19aa03c79256f63e5
-  data.tar.gz: 2e6b5289e68ee0a3d3549f6c8befec0130f1821d
+  metadata.gz: fded34de11c00d46011c9876c65ad8b334a0559a
+  data.tar.gz: aba9dbae4d56919578678e16ad8984c826ab6c12
 SHA512:
-  metadata.gz: 3dad077e59925dd1265286f7c0abcf6524b5c6830720c92657d11ee59e0c5b33898236af2a84d56cbfad9f2111154984343d8b3b6b1b1712f485546d0983af32
-  data.tar.gz: 863c175bd7987a5dc24067556bf3c1a3238ca64c81cbf3ed6cd06e87478a1ff8ea04e07c9b0659ffcff7afac6dfb7ab648d3414d6dba81083f95a2c1f8df6214
+  metadata.gz: 6edc7788c2df4fb07eaef376ae06d35d07d15fda5ab7a6dc677bdd071439ff761d2f036fc3ec7a1c5c6d816ce7de119a0940176e511bc0e417c77bcada868d19
+  data.tar.gz: a641b0baa915b6a46d1345afb0557f2053f6f7757eec4eef24818ae31506ecae7e2be46766ab1fd78dbe261bcc5b1f307cd2ab865ed89df9ce91ade4734c74a9

data/README.md

@@ -35,12 +35,32 @@ account = Googol::YoutubeAccount.new auth_params
 # like the video 'Tongue'  by R.E.M.
 account.like! video_id: 'Kd5M17e7Wek'
 
-# subscribes to Fullscreen’s channel
-account.subscribe_to! channel_id: 'UCxO1tY8h1AhOz0T4ENwmpow' # => subscribes to Fullscreen’s channel
+# subscribe to Fullscreen’s channel
+account.subscribe_to! channel_id: 'UCxO1tY8h1AhOz0T4ENwmpow'
 
-# add the video 'Tongue' to your 'Favorite Music Videos' playlist
-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
+# unsubscribe from Fullscreen’s channel
+account.unsubscribe_from! channel_id: 'UCxO1tY8h1AhOz0T4ENwmpow'
+
+# create a playlist called "Fullscreen"
+account.create_playlist! title: "Fullscreen"
+
+# find the first playlist with "Fullscreen" in the title
+account.find_playlist_by title: /Fullscreen/i
+
+# delete all playlists with "Fullscreen" in the description
+account.delete_playlists! description: /Fullscreen/i
+
+# add the video 'Tongue' by R.E.M. to your 'Fullscreen' playlist
+playlist_id = account.find_or_create_playlist_by title: 'Fullscreen'
+account.add_item_to! playlist_id, video_id: 'Kd5M17e7Wek'
+
+# add a list of 3 videos by R.E.M. to your 'Fullscreen' playlist
+playlist_id = account.find_or_create_playlist_by title: 'Fullscreen'
+account.add_item_to! playlist_id, ['Kd5M17e7Wek', '3D1zWC1hs0', 'G2BCrByfZ74']
+
+# remove all the items from your 'Fullscreen' playlist
+playlist_id = account.find_or_create_playlist_by title: 'Fullscreen'
+account.remove_all_items_from! playlist_id
 ```
 
 The full documentation is available at [rubydoc.info](http://rubydoc.info/github/fullscreeninc/googol/master/frames).
@@ -58,7 +78,7 @@ Use `Googol::GoogleAccount` to send and retrieve data to Google,
 impersonating an existing Google account.
 
 Available instance methods are `id`, `email`, `verified_email`, `name`,
-`given_name`, `family_name`, `link`, `picture`, `gender`, `locale`, and `hd`.
+`given_name`, `family_name`, `link`, `picture`, `gender`, and `locale`.
 
 These methods require user authentication (see below).
 
@@ -145,7 +165,7 @@ To install on your system, run
 
 To use inside a bundled Ruby project, add this line to the Gemfile:
 
-    gem 'googol', '~> 0.2.1'
+    gem 'googol', '~> 0.3.0'
 
 Since the gem follows [Semantic Versioning](http://semver.org),
 indicating the full version in your Gemfile (~> *major*.*minor*.*patch*)

data/lib/googol/google_account.rb

@@ -33,7 +33,6 @@ module Googol
     #   * :picture [String] The URL of the account’s profile picture.
     #   * :gender [String] The account’s gender
     #   * :locale [String] The account’s preferred locale.
-    #   * :hd [String] The hosted domain name for the accounts’s Google Apps.
     def info
       @info ||= request! auth: credentials[:access_token],
         host: 'https://www.googleapis.com', path: '/oauth2/v2/userinfo'
@@ -59,7 +58,6 @@ module Googol
     attribute :picture
     attribute :gender
     attribute :locale
-    attribute :hd
 
     # Set the scopes to grant access to Google user profile and email
     #

data/lib/googol/requestable.rb

@@ -20,13 +20,20 @@ module Googol
       http = Net::HTTP.new url.host, url.port
       http.use_ssl = true
       request = case params[:method]
-        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]
+      when :post
+        if params[:json]
+          Net::HTTP::Post.new params[:path], initheader = {'Content-Type' =>'application/json'}
+        else
+          Net::HTTP::Post.new params[:path]
+        end
+      when :delete
+        Net::HTTP::Delete.new params[:path]
+      when :put
+        if params[:json]
+          Net::HTTP::Put.new params[:path], initheader = {'Content-Type' =>'application/json'}
+        end
+      else
+        Net::HTTP::Get.new params[:path]
       end
       if params[:json]
         request.body = params[:body].to_json

data/lib/googol/version.rb

@@ -1,3 +1,3 @@
 module Googol
-  VERSION = '0.2.1'
+  VERSION = '0.3.0'
 end

data/lib/googol/youtube_account.rb

@@ -1,5 +1,8 @@
 require 'googol/authenticable'
 require 'googol/readable'
+require 'googol/youtube_account/playlists'
+require 'googol/youtube_account/playlist_items'
+require 'googol/youtube_account/subscriptions'
 
 module Googol
   # Provides read & write access to a Youtube account (also known as Channel).
@@ -19,6 +22,9 @@ module Googol
   class YoutubeAccount
     include Authenticable
     include Readable
+    include Playlists
+    include PlaylistItems
+    include Subscriptions
     # Return the profile info of a Youtube account/channel.
     #
     # @see https://developers.google.com/youtube/v3/docs/channels#resource
@@ -55,126 +61,8 @@ module Googol
       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}}}
-    rescue Googol::RequestError => e
-      raise e unless e.to_s =~ /subscriptionDuplicate/
-    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
-
   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|

data/lib/googol/youtube_account/playlist_items.rb

@@ -0,0 +1,92 @@
+module Googol
+  # Separate module to group YoutubeAccount methods related to playlist items.
+  module PlaylistItems
+    # Add an item to a Youtube playlist.
+    #
+    # @param [String] playlist_id The ID of the playlist to add videos to
+    # @param [Hash] target The item to add to the playlist
+    # @option target [String] :video_id The ID of the item (when item is video)
+    #
+    # @note Google API allows other types of items to be added to a playlist
+    #       but for now we are just using videos. If you need other types,
+    #       we can just expand this method.
+    #
+    # @see https://developers.google.com/youtube/v3/docs/playlistItems/insert
+    #
+    def add_item_to!(playlist_id, item = {})
+      resource = {videoId: fetch!(item, :video_id), kind: 'youtube#video'}
+      youtube_request! method: :post, json: true,
+        path: '/playlistItems?part=snippet',
+        body: {snippet: {playlistId: playlist_id, resourceId: resource}}
+    end
+
+    # Remove all items from a Youtube playlist.
+    #
+    # @param [String] playlist_id The ID of the playlist to add videos to
+    # @param [Hash] filters The filter to remove the playlist items by.
+    #
+    # @see https://developers.google.com/youtube/v3/docs/playlistItems/delete
+    #
+    def remove_all_items_from!(playlist_id, filters = {})
+      items_of(playlist_id, filters).map do |item_id|
+        remove_item_from! playlist_id, item_id
+      end
+    end
+
+    # Adds an array of videos to a Youtube playlist.
+    #
+    # @param [String] playlist_id The ID of the playlist to add videos to
+    # @param [Array of String] video_ids The IDs of the videos to add
+    #
+    # @see https://developers.google.com/youtube/v3/docs/playlistItems/insert
+    #
+    def add_videos_to!(playlist_id, video_ids = [])
+      video_ids.map{|video_id| add_item_to! playlist_id, video_id: video_id}
+    end
+
+  private
+
+    # List all items of a Youtube playlist.
+    #
+    # @param [String] playlist_id The ID of the playlist to add videos to
+    #
+    # @return [Array of Hashes] Items of the playlist
+    #
+    # @note Google API does not have a "search" endpoint, therefore we have
+    # to scan the list of playlist items page by page, limiting at 10 pages to
+    # prevent this function from running forever (50 items per page).
+    #
+    # @see https://developers.google.com/youtube/v3/docs/playlistItems/list
+    #
+    def items_of(playlist_id, filters = {})
+      page = filters.delete(:page) || 1
+
+      path = "/playlistItems?part=id,snippet&playlistId=#{playlist_id}"
+      path << "&maxResults=#{filters.delete(:max) || 50 }"
+      path << "&pageToken=#{filters.delete :token}" if filters[:token]
+
+      response = youtube_request! path: path
+      items = response[:items].map{|item| item[:id]}
+
+      more_items = if page < 10 && token = response[:nextPageToken]
+        items_of playlist_id, page: page + 1, token: token
+      else
+        []
+      end
+
+      items + more_items
+    end
+
+    # Remove an item from a playlist.
+    #
+    # @param [String] playlist_id The ID of the playlist to remove items from
+    # @param [String] playlist_item_id The ID of the item to remove
+    #
+    # @see https://developers.google.com/youtube/v3/docs/playlistItems/delete
+    #
+    def remove_item_from!(playlist_id, item_id)
+      youtube_request! method: :delete, code: 204,
+        path: "/playlistItems?id=#{item_id}"
+    end
+  end
+end

data/lib/googol/youtube_account/playlists.rb

@@ -0,0 +1,196 @@
+module Googol
+  # Separate module to group YoutubeAccount methods related to playlists.
+  module Playlists
+    # Creates a playlist for a Youtube account
+    #
+    # @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 = {})
+      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}}
+      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 + 1, token: token
+      end
+    end
+
+    # Return the first playlist of the Youtube account matching the attributes
+    # or creates one if none is found
+    #
+    # @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_or_create_playlist_by(filters = {})
+      find_playlist_by(filters) || create_playlist!(filters)
+    end
+
+    # Updates a playlist for a Youtube account
+    #
+    # @param [String] playlist_id The ID of the playlist to update
+    # @param [Hash] attributes The attributes to update in the playlist
+    # @option attributes [String] :title Title of the playlist
+    # @option attributes [String] :description Description of the playlist
+    # @option attributes [Boolean] :public Should the playlist be public
+    #
+    # @note For some unknown reason, Google API *requires* to pass the new
+    #       title, even if it does not change. Therefore the attrs[:title]
+    #       *is required*, otherwise Google API fails (sigh)
+
+    # @return [String] The ID of the playlist
+    #
+    # @see https://developers.google.com/youtube/v3/docs/playlists/update
+    #
+    def update_playlist!(playlist_id, attrs = {})
+      body = {id: playlist_id}
+      parts = []
+
+      if attrs.key? :title
+        body[:snippet] = {title: attrs[:title]}
+        parts << 'snippet'
+      else
+        raise RequestError, "Cannot update a playlist without a title"
+      end
+
+      if attrs.key? :description
+        body[:snippet][:description] = attrs[:description]
+      end
+
+      if attrs.key? :public
+        body[:status] = {privacyStatus: attrs[:public] ? 'public' : 'private'}
+        parts << 'status'
+      end
+
+      playlist = youtube_request! json: true, method: :put,
+        path: "/playlists?part=#{parts.join ','}", body: body
+      playlist[:id]
+    end
+
+    # Delete all the playlists of the Youtube account matching the 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
+    #
+    # @example account.delete_playlists! title: 'Title'
+    # @example account.delete_playlists! description: /desc/
+    #
+    def delete_playlists!(filters = {})
+      playlists(filters).map{|playlist_id| delete_playlist! playlist_id}
+    end
+
+  private
+
+    # List all the playlists of the Youtube account matching the 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 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).
+    #
+    # @example account.playlists title: 'Title'
+    # @example account.playlists description: /desc/
+    #
+    # @return [Array of Strings] The IDs of the playlists
+    def playlists(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
+      playlists = response[:items].select do |p|
+        playlist_matches? p, filters
+      end.map{|p| p[:id]}
+
+      more_playlists = if page < 10 && token = response[:nextPageToken]
+        playlists filters.merge(page: page + 1, token: token)
+      else
+        []
+      end
+
+      playlists + more_playlists
+    end
+
+    # Deletes a playlist of a Youtube account.
+    #
+    # @param [String] playlist_id The ID of the playlist to delete
+    #
+    # @see https://developers.google.com/youtube/v3/docs/playlists/delete
+    #
+    def delete_playlist!(playlist_id)
+      youtube_request! method: :delete, code: 204,
+        path: "/playlists?id=#{playlist_id}"
+    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
+  end
+end

data/lib/googol/youtube_account/subscriptions.rb

@@ -0,0 +1,145 @@
+module Googol
+  # Separate module to group YoutubeAccount methods related to subscriptions.
+  module Subscriptions
+    # Subscribe a Youtube account to a channel. If the account is already
+    # subscribed, raise an error.
+    #
+    # @param [Hash] channel The channel for the 'subscribe' activity
+    # @option channel [String] :channel_id The ID of the channel to subscribe to
+    #
+    # @return [String] The ID of the new channel subscription
+    #
+    # @see https://developers.google.com/youtube/v3/docs/subscriptions/insert
+    #
+    def subscribe_to!(channel = {})
+      channel_id = fetch! channel, :channel_id
+      youtube_request! path: '/subscriptions?part=snippet', json: true,
+        method: :post, body: {snippet: {resourceId: {channelId: channel_id}}}
+    end
+
+    # Subscribe a Youtube account to a channel. If the account is already
+    # subscribed, return the existing channel subscription ID.
+    #
+    # @param [Hash] channel The channel for the 'subscribe' activity
+    # @option channel [String] :channel_id The ID of the channel to subscribe to
+    #
+    # @return [String] The ID of the new or existing channel subscription
+    #
+    # @raise [Googol::RequestError] if the subscription does not go through,
+    #   unless the error is that the user is already subscribed to the channel.
+    #
+    # @see https://developers.google.com/youtube/v3/docs/subscriptions/insert
+    #
+    def subscribe_to(channel = {})
+      subscribe_to! channel
+    rescue Googol::RequestError => e
+      if e.to_s =~ /subscriptionDuplicate/
+        find_subscription_by channel
+      else
+        raise e
+      end
+    end
+
+    # Unsubscribe a Youtube account from a channel. If the account is not
+    # subscribed, raise an error.
+    #
+    # @param [Hash] channel The channel for the 'subscribe' activity
+    # @option channel [String] :channel_id The ID of the channel to unsubscribe from
+    #
+    # @raise [Googol::RequestError] if the unsubscription does not go through
+    #
+    # @see https://developers.google.com/youtube/v3/docs/subscriptions/delete
+    #
+    def unsubscribe_from!(channel = {})
+      delete_subscription!(find_subscription_by channel)
+    end
+
+    # Unsubscribe a Youtube account from a channel. If the account is not
+    # subscribed, ignore the request.
+    #
+    # @param [Hash] channel The channel for the 'subscribe' activity
+    # @option channel [String] :channel_id The ID of the channel to unsubscribe from
+    #
+    # @raise [Googol::RequestError] if the unsubscription does not go through,
+    #   unless the error is that the user was not subscribed to the channel.
+    #
+    # @see https://developers.google.com/youtube/v3/docs/subscriptions/delete
+    #
+    def unsubscribe_from(channel = {})
+      unsubscribe_from! channel
+    rescue Googol::RequestError => e
+      if e.to_s =~ /subscriptionNotFound/
+        true
+      else
+        raise e
+      end
+    end
+
+  private
+
+    # Return the first subscription of the Youtube account for the given filters.
+    #
+    # @param [Hash] filters The channel subscribed to (plus private options)
+    # @option filters [String] :channel_id The ID of the channel subscribed to
+    # @option filters [Integer] :retries Number of retries is subscription not found
+    #
+    # @note Google API does not have a "search" endpoint, therefore we have
+    # to scan the list of subscriptions page by page, limiting at 10 pages to
+    # prevent this function from running forever (50 subscriptions per page).
+    #
+    # @note Google API must have some caching layer by which if we try to
+    # delete a subscription that we just created, we encounter an error.
+    # To overcome this, if we don't find a playlist, we can pass a +retries+
+    # parameter to try the same request at intervals of 5 seconds.
+    #
+    # @return [String or nil] The ID of the subscription (or nil if not found)
+    def find_subscription_by(filters = {})
+      page = filters.delete(:page) || 1
+
+      path = "/subscriptions?part=id,snippet&mine=true"
+      path << "&maxResults=#{filters.delete(:max) || 50 }"
+      path << "&pageToken=#{filters.delete :token}" if filters[:token]
+
+      response = youtube_request! path: path
+      items = response[:items]
+
+      if subscription = items.find{|s| subscription_belongs_to? s, filters}
+        subscription[:id]
+      elsif page < 10 && token = response[:nextPageToken]
+        find_subscription_by filters.merge page: page + 1, token: token
+      elsif filters.fetch(:retries, 0) > 0
+        sleep 5 * filters[:retries]
+        find_subscription_by filters.merge retries: filters[:retries] - 1
+      end
+    end
+
+    # Checks if the subscription belongs to the given channel.
+    #
+    # @param [Hash] channel The channel the subscription might belong to
+    # @option channel_id [String] The ID of the channel
+    #
+    # @example Given a subscription x with channel_id: 'ABCDE'
+    #     subscription_belongs_to? x, channel_id: 'ABCDE' # => true
+    #     subscription_belongs_to? x, channel_id: '12345' # => false
+    #
+    # @return [Boolean] Whether the subscription belongs to the channel
+    def subscription_belongs_to?(subscription, channel = {})
+      channel_id = fetch! channel, :channel_id
+      subscription[:snippet][:resourceId][:channelId] == channel_id
+    end
+
+    # Delete a channel subscription for the Youtube account. If the
+    # subscription does not exist, raise an error.
+    #
+    # @param [String] subscription_id The channel subscription ID to delete
+    #
+    # @raise [Googol::RequestError] if the unsubscription does not go through
+    #
+    # @see https://developers.google.com/youtube/v3/docs/subscriptions/delete
+    #
+    def delete_subscription!(subscription_id, retries = 5)
+      youtube_request! method: :delete, code: 204,
+        path: "/subscriptions?id=#{subscription_id}"
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: googol
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-10 00:00:00.000000000 Z
+date: 2014-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -98,6 +98,9 @@ files:
 - lib/googol/server_tokens.rb
 - lib/googol/version.rb
 - lib/googol/youtube_account.rb
+- lib/googol/youtube_account/playlist_items.rb
+- lib/googol/youtube_account/playlists.rb
+- lib/googol/youtube_account/subscriptions.rb
 - lib/googol/youtube_resource.rb
 homepage: https://github.com/fullscreeninc/googol
 licenses: