how_many 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 38abb29c9d453fd4078012357db7173aeef5b609
-  data.tar.gz: 324a862dd5f0792d7eb462cc6f07f138ea688cc7
+  metadata.gz: 12a9c6f32f4ee8e7d11277db9483378a5bfb8b47
+  data.tar.gz: 74d0a0742687ed7e4341607c88ea263f67198351
 SHA512:
-  metadata.gz: 0b603c906a9a6aa532d2178091a506805d65fa5c70d1c606ed22a4e1569b8044d041df6b497a4e912a08f466c9e889dc617fc49daf7f36e8c012f7abcdf7582f
-  data.tar.gz: f018626e4119c5c6371c63912a6d17b57ebebf4d0ddad259bf68891f7ae8775c720bd37285776705a3c493eda8e0cbcd1d977f575cc14f2653f8bac586baf9ba
+  metadata.gz: 6764d4cc3a2e3f583f67e10d587a3b6c8b6890471563cf6a580ab49f1fc25743245a54310613a48180c2b926beeb5c3748631b554c090ecd9c81ec55970951ed
+  data.tar.gz: 614aa5dc50fc09d1d34383f8d07ce4f26214515654ea5a18a40fd3012d788b45e3fa809b0ce33821fc17d54226b74e76064d786b4fa4afc2462d3219d810b628

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--fail-fast

data/.yardopts

@@ -0,0 +1,2 @@
+--no-private
+lib/**/*.rb

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+For more information about changelogs, check
+[Keep a Changelog](http://keepachangelog.com) and
+[Vandamme](http://tech-angels.github.io/vandamme).
+
+## 0.1.0 - 2014-10-27
+
+* [FEATURE] Initial release with `views(channel_id: ...)` method

data/Gemfile

@@ -1,4 +1,4 @@
 source 'https://rubygems.org'
-
+gem 'pry'
 # Specify your gem's dependencies in how_many.gemspec
 gemspec

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2014 claudiob
+Copyright (c) 2014 Fullscreen Inc.
 
 MIT License
 

data/README.md

@@ -1,29 +1,104 @@
-# HowMany
+How many views do the most recent videos of a YouTube channel have?
+===================================================================
 
-TODO: Write a gem description
+HowMany helps you write apps that need to know how many times the videos of
+a CMS-partnered YouTube channel were viewed.
 
-## Installation
+After [registering your app](#configuring-your-app), you can run the only
+command currently provided by the gem:
 
-Add this line to your application's Gemfile:
+```ruby
+HowMany.views channel_id: 'UCxO1tY8h1AhOz0T4ENwmpow' # => 139
+```
 
-    gem 'how_many'
+How to install
+==============
 
-And then execute:
+To install on your system, run
 
-    $ bundle
+    gem install how_many
 
-Or install it yourself as:
+To use inside a bundled Ruby project, add this line to the Gemfile:
 
-    $ gem install how_many
+    gem 'how_many', '~> 0.1.0'
 
-## Usage
+Since the gem follows [Semantic Versioning](http://semver.org),
+indicating the full version in your Gemfile (~> *major*.*minor*.*patch*)
+guarantees that your project won’t occur in any error when you `bundle update`
+and a new version of HowMany is released.
 
-TODO: Write usage instructions here
+Available methods
+=================
 
-## Contributing
+views
+-----
 
-1. Fork it ( https://github.com/[my-github-username]/how_many/fork )
-2. Create how_many feature branch (`git checkout -b my-new-feature`)
-3. Commit how_many changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+Use `HowMany.views` to retrieve the median views for the videos of a channel:
+
+```ruby
+require 'how_many'
+
+# get the median views of the last videos of a Fullscreen-partnered channel
+HowMany.views(channel_id: 'UCSBzN-I43cp0-xekSFW5mkQ')
+#=> 12534.5
+
+# get the same value for a channel with not enough videos
+HowMany.views(channel_id: 'UCI7ajRBjOkCUvfQleFUfelA')
+#=> raise error HowMany::NotEnoughVideos
+
+# get the same value for PewDiePie
+HowMany.views(channel_id: 'UC-lHJZR3Gqxm24_Vd_AJ5Yw')
+#=> raise error HowMany::Unauthorized
+```
+
+*The methods above require to be authenticated as a YouTube Content Partner account (see below).*
+
+
+Configuring your app
+====================
+
+In order to use HowMany you must be able to authenticate as a YouTube CMS owner.
+You will only be able to retrieve the views for channels partnered with your CMS.
+
+In the [Google Developers Console](https://console.developers.google.com),
+find or create an app that can be used to obtain a refresh token for the
+YouTube CMS owner.
+
+Copy Client ID and Client secret from the app and add them together with the
+refresh token to you code with the following initializer (replacing with your
+own keys):
+
+```ruby
+HowMany.configure do |config|
+  config.client_id = '1234567890.apps.googleusercontent.com'
+  config.client_secret = '1234567890'
+  config.refresh_token = '1/1234567890'
+end
+```
+
+As an alternative to the approach above, you can configure your app with
+variables. Setting the following environment variables:
+
+```bash
+export HOW_MANY_CLIENT_ID="1234567890.apps.googleusercontent.com"
+export HOW_MANY_CLIENT_SECRET="1234567890"
+export HOW_MANY_REFRESH_TOKEN="1/1234567890"
+```
+
+is equivalent to the approach above.
+If a variable is set in both places, then `HowMany.configure` takes precedence.
+
+
+How to test
+===========
+
+Set the following environment variables:
+
+* `HOW_MANY_TEST_CLIENT_ID` the client ID of your registered YouTube app.
+* `HOW_MANY_TEST_CLIENT_SECRET` the client secret of your registered YouTube app.
+* `HOW_MANY_TEST_REFRESH_TOKEN` the refresh token of the test YouTube CMS user.
+
+Then run `rspec`.
+
+Whenever you change the code, make sure all the tests pass and the code
+coverage is 100% before submitting a pull request. Thanks.

data/how_many.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'how_many/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "how_many"
+  spec.version       = HowMany::VERSION
+  spec.authors       = ["claudiob"]
+  spec.email         = ["claudiob@gmail.com"]
+  spec.summary       = %q{How many views does a YouTube channel have?}
+  spec.description   = %q{Retrieve analytics data for YouTube channels.}
+  spec.homepage      = "https://github.com/fullscreen/how_many"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  # To access YouTube API
+  spec.add_development_dependency 'yt', '~> 0.13.7'
+
+  # For development / Code coverage / Documentation
+  spec.add_development_dependency 'bundler', '~> 1.7'
+  spec.add_development_dependency 'rspec', '~> 3.1'
+  spec.add_development_dependency 'rake', '~> 10.3'
+  spec.add_development_dependency 'yard', '~> 0.8.7'
+  spec.add_development_dependency 'coveralls', '~> 0.7.1'
+end

data/lib/how_many/channel.rb

@@ -0,0 +1,76 @@
+require 'yt'
+require 'how_many/config'
+require 'how_many/errors'
+
+module HowMany
+  # Abstracts a YouTube channel.
+  class Channel
+    # Initialize a Channel instance.
+    def initialize(attrs = {})
+      @id = attrs[:channel_id]
+      @days = attrs.fetch :days, 14
+      @video_count = attrs.fetch :video_count, 10
+    end
+
+    # Return the unique YouTube channel ID.
+    attr_reader :id
+
+    # Return the number of days since a video was first published for which
+    # the number of views has to be retrieved.
+    attr_reader :days
+
+    # Return the number of videos for which the views have to be retrieved.
+    attr_reader :video_count
+
+    # Return the median number of views that the `@video_count` most recent
+    # videos of the channel have received in the first `@days` days since
+    # they were published. Excludes videos that were published less than
+    # `@days + 2` days ago, since analytics data might not be available yet.
+    def median_recent_video_views
+      raise NotEnoughVideos if yt_videos.size < video_count
+      views_by_day = yt_videos.map do |v|
+        v.views since: v.published_at, until: (v.published_at + days.days)
+      end
+      views_by_video = views_by_day.map(&:values).map(&:sum)
+      median views_by_video
+    end
+
+  private
+
+    def median(array)
+      (array[(array.length/2) - 1] + array[array.length/2]) / 2.to_f
+    end
+
+    def yt_videos
+      conditions = {published_before: (days + 2).days.ago.utc.iso8601(3)}
+      @yt_videos ||= yt_channel.videos.where(conditions).first(video_count)
+    rescue Yt::Errors::Forbidden
+      raise Unauthorized
+    end
+
+    def yt_channel
+      @yt_channel ||= Yt::Channel.new id: id, auth: yt_content_owner
+    end
+
+    def yt_content_owner
+      @yt_content_owner ||= yt_account.content_owners.find do |content_owner|
+        channel = Yt::Channel.new id: id, auth: content_owner
+        channel.content_owner == content_owner.owner_name
+      end
+    rescue Yt::Errors::MissingAuth
+      raise Unauthorized
+    end
+
+    def yt_account
+      @yt_account ||= Yt::Account.new refresh_token: refresh_token
+    end
+
+    def refresh_token
+      Yt.configure do |config|
+        config.client_id = HowMany.configuration.client_id
+        config.client_secret = HowMany.configuration.client_secret
+      end
+      HowMany.configuration.refresh_token
+    end
+  end
+end

data/lib/how_many/config.rb

@@ -0,0 +1,43 @@
+require 'yt/models/configuration'
+
+module HowMany
+  # Provides an object to store global configuration settings.
+  class Configuration
+    # @return [String] the Client ID for the CMS-enabled YouTube app.
+    # @see https://console.developers.google.com Google Developers Console
+    attr_accessor :client_id
+
+    # @return [String] the Client Secret for the CMS-enabled YouTube app.
+    # @see https://console.developers.google.com Google Developers Console
+    attr_accessor :client_secret
+
+    # @return [String] the refresh token for the CMS user.
+    attr_accessor :refresh_token
+
+    # Initialize the global configuration settings, using the values of
+    # the specified following environment variables by default.
+    def initialize
+      @client_id = ENV['HOW_MANY_CLIENT_ID']
+      @client_secret = ENV['HOW_MANY_CLIENT_SECRET']
+      @refresh_token = ENV['HOW_MANY_REFRESH_TOKEN']
+    end
+  end
+
+  # Provides methods to read and write global configuration settings.
+  module Config
+    # Yields the global configuration to the given block.
+    def configure
+      yield configuration if block_given?
+    end
+
+    # Returns the global {HowMany::Models::Configuration} object.
+    def configuration
+      @configuration ||= HowMany::Configuration.new
+    end
+  end
+
+  # @note Config is the only module auto-loaded in the HowMany module,
+  #       in order to have a syntax as easy as HowMany.configure
+
+  extend Config
+end

data/lib/how_many/errors.rb

@@ -0,0 +1,15 @@
+module HowMany
+  # Generic base Error
+  class Error < StandardError
+  end
+
+  # Raised when trying to calculate the median video views for a channel that
+  # does not have enough videos to calculate a valid median.
+  class NotEnoughVideos < Error
+  end
+
+  # Raised when trying to access the analytics of a channel for which the
+  # analytics cannot be accessed.
+  class Unauthorized < Error
+  end
+end

data/lib/how_many/version.rb

@@ -1,3 +1,4 @@
 module HowMany
-  VERSION = "0.0.1"
+  # Version of the how_many gem.
+  VERSION = '0.1.0'
 end

data/lib/how_many/views.rb

@@ -0,0 +1,14 @@
+require 'how_many/channel'
+
+module HowMany
+  # Return the median number of views of the videos of a YouTube channel.
+  # Valid options are: channel_id (unique identifier of a YouTube channel),
+  # days (the range of days for which to retrieve the video views) and
+  # video_count (for how many recent videos the median should be calculated).
+  def views(options = {})
+    channel = Channel.new options
+    channel.median_recent_video_views
+  end
+
+  module_function :views
+end

data/lib/how_many.rb

@@ -1,5 +1,5 @@
-require "how_many/version"
+require 'how_many/views'
 
+# Helps creating apps that need to retrieve view counts for YouTube videos.
 module HowMany
-  # HowMany code goes here...
-end
+end

data/spec/how_many/views_spec.rb

@@ -0,0 +1,46 @@
+require 'spec_helper'
+require 'how_many'
+
+describe 'HowMany.views' do
+  subject(:channel_views) { HowMany.views channel_id: channel_id }
+
+  context 'after having authenticated as Fullscreen CMS' do
+    before do
+      HowMany.configure do |config|
+        config.client_id = ENV['HOW_MANY_TEST_CLIENT_ID']
+        config.client_secret = ENV['HOW_MANY_TEST_CLIENT_SECRET']
+        config.refresh_token = ENV['HOW_MANY_TEST_REFRESH_TOKEN']
+      end
+    end
+
+    context 'given a Fullscreen-partnered channels with many videos' do
+      let(:channel_id) { 'UCSBzN-I43cp0-xekSFW5mkQ' }
+      it { expect(channel_views).to be_a Float }
+    end
+
+    context 'given a Fullscreen-partnered channels with few videos' do
+      let(:channel_id) { 'UCjA3ooUo_j8r2d5a5g9YrVA' }
+      it { expect{channel_views}.to raise_error HowMany::NotEnoughVideos }
+    end
+
+    context 'given a non-Fullscreen-partnered channel' do
+      let(:channel_id) { 'UC-lHJZR3Gqxm24_Vd_AJ5Yw' }
+      it { expect{channel_views}.to raise_error HowMany::Unauthorized }
+    end
+  end
+
+  context 'without having authenticated' do
+    before do
+      HowMany.configure do |config|
+        config.client_id = nil
+        config.client_secret = nil
+        config.refresh_token = nil
+      end
+    end
+
+    context 'given any channel' do
+      let(:channel_id) { 'UCSBzN-I43cp0-xekSFW5mkQ' }
+      it { expect{channel_views}.to raise_error HowMany::Unauthorized }
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,15 @@
+require 'simplecov'
+require 'coveralls'
+
+SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter[
+  SimpleCov::Formatter::HTMLFormatter,
+  Coveralls::SimpleCov::Formatter
+]
+SimpleCov.start
+
+Dir['./spec/support/**/*.rb'].each {|f| require f}
+
+RSpec.configure do |config|
+  config.order = 'random'
+  config.run_all_when_everything_filtered = false
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: how_many
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - claudiob
@@ -10,35 +10,91 @@ bindir: bin
 cert_chain: []
 date: 2014-10-27 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: yt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.7
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.7
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: '1.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.3'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.8.7
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.7
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-description: Write a longer description. Optional.
+        version: 0.7.1
+description: Retrieve analytics data for YouTube channels.
 email:
 - claudiob@gmail.com
 executables: []
@@ -46,14 +102,23 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".rspec"
+- ".yardopts"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
-- how_many,.gemspec
+- how_many.gemspec
 - lib/how_many.rb
+- lib/how_many/channel.rb
+- lib/how_many/config.rb
+- lib/how_many/errors.rb
 - lib/how_many/version.rb
-homepage: ''
+- lib/how_many/views.rb
+- spec/how_many/views_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/fullscreen/how_many
 licenses:
 - MIT
 metadata: {}
@@ -76,5 +141,8 @@ rubyforge_project:
 rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
-summary: Write a short summary. Required.
-test_files: []
+summary: How many views does a YouTube channel have?
+test_files:
+- spec/how_many/views_spec.rb
+- spec/spec_helper.rb
+has_rdoc: 

data/how_many,.gemspec

@@ -1,23 +0,0 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'how_many/version'
-
-Gem::Specification.new do |spec|
-  spec.name          = "how_many"
-  spec.version       = HowMany::VERSION
-  spec.authors       = ["claudiob"]
-  spec.email         = ["claudiob@gmail.com"]
-  spec.summary       = %q{Write a short summary. Required.}
-  spec.description   = %q{Write a longer description. Optional.}
-  spec.homepage      = ""
-  spec.license       = "MIT"
-
-  spec.files         = `git ls-files -z`.split("\x0")
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
-  spec.require_paths = ["lib"]
-
-  spec.add_development_dependency "bundler", "~> 1.6"
-  spec.add_development_dependency "rake"
-end