bbc_redux 0.4.0.pre

data/lib/bbc/redux/channel_category.rb

@@ -0,0 +1,36 @@
+require 'virtus'
+
+module BBC
+  module Redux
+
+    # Redux API Channel Category Object
+    #
+    # @example Properties of the channel category object
+    #
+    #   category = redux_client.channel_categories.first
+    #
+    #   category.description  #=> String
+    #   category.id           #=> Integer
+    #   category.priority     #=> Integer
+    #
+    # @author Matt Haynes <matt.haynes@bbc.co.uk>
+    class ChannelCategory
+
+      include Virtus.value_object
+
+      # @!attribute [r] description
+      # @return [String] category's description, e.g. 'BBC TV'
+      attribute :description, String
+
+      # @!attribute [r] id
+      # @return [Integer] category's id
+      attribute :id, Integer
+
+      # @!attribute [r] priority
+      # @return [String] category's priority, a hint for display in views
+      attribute :priority, Integer
+
+    end
+
+  end
+end

data/lib/bbc/redux/client.rb

@@ -0,0 +1,302 @@
+require 'date'
+require 'json'
+require 'typhoeus'
+
+module BBC
+  module Redux
+
+    # Redux API Client
+    #
+    # @example Initialize client with either username and password or token
+    #
+    #   client = BBC::Redux::Client.new({
+    #     :username => 'username',
+    #     :password => 'password',
+    #   })
+    #
+    #   client = BBC::Redux::Client.new :token => 'some-token'
+    #
+    # @example Using the client to retrieve data
+    #
+    #   client.asset('5966413090093319525') #=> BBC::Redux::Asset
+    #   client.channel_categories           #=> Array<BBC::Redux::ChannelCategory>
+    #   client.channels                     #=> Array<BBC::Redux::Channel>
+    #   client.schedule(Date.today)         #=> Array<BBC::Redux::Asset>
+    #   client.search(:name => 'Pingu')     #=> BBC::Redux::SearchResults
+    #   client.user                         #=> BBC::Redux::User
+    #
+    # @example Call logout once finished to destroy your session
+    #
+    #   client.logout
+    #
+    # @author Matt Haynes <matt.haynes@bbc.co.uk>
+    class Client
+
+      # Raised when backend HTTP API returns a 403, indicates you are either
+      # trying to access some content that is unavailable to you, or your token
+      # and session has expired.
+      class ForbiddenException < Exception; end
+
+      # Raised when backend HTTP API returns a 4XX or 5XX status other than
+      # 403, indicates an error within the HTTP API or bug in this library
+      class HttpException < Exception; end
+
+      # Raised when backend HTTP API returns a body that does not parse as json
+      class JsonParseException < Exception; end
+
+      # @!attribute [r] http
+      # @return [Object] http client, by default this is Typhoeus
+      attr_reader :http
+
+      # @!attribute [r] token
+      # @return [String] token for current session
+      attr_reader :token
+
+      # @!attribute [r] host
+      # @return [String] API HTTP host
+      attr_reader :host
+
+      # Client must be initialized with either a username and password
+      # combination or a token
+      #
+      # @param [Hash] options the options to create client with
+      # @option options [String] :username username of a redux account
+      # @option options [String] :password password of a redux account
+      # @option options [String] :token token for an existing redux session
+      # @option options [String] :host (https://i.bbcredux.com) api host
+      # @option options [Object] :http (Typhoeus) The http client, can be
+      #   overidden but expects method .post to return an object looking like
+      #   Typhoeus::Response (code, headers, body, etc)
+      def initialize(options = {})
+        @host  = options[:host] || 'https://i.bbcredux.com'
+        @http  = options[:http] || Typhoeus
+        @token = options[:token] || begin
+          username = options[:username]
+          password = options[:password]
+
+          if username && password
+            data = data_for(:login, {
+              :username => username, :password => password
+            })
+
+            @token = data.fetch('token')
+          else
+            raise 'Supply either :token or :username and :password options'
+          end
+        end
+      end
+
+      # Fetch asset object
+      # @param [String] identifier either disk reference or uuid
+      # @see BBC::Redux::Asset
+      # @return [BBC::Redux::Asset, nil] the asset
+      def asset(identifier)
+        if identifier =~ /^\d{19}$/
+          params = { :reference => identifier }
+        else
+          params = { :uuid => identifier }
+        end
+
+        build :asset, :using => data_for(:asset, params)
+      end
+
+      # Fetch available channels for this session
+      # @see BBC::Redux::Channel
+      # @return [Array<BBC::Redux::Channel>] array of channels
+      def channels
+        build :channels, :using => data_for(:channels)
+      end
+
+      # Fetch available channel categories for this session
+      # @see BBC::Redux::ChannelCategory
+      # @return [Array<BBC::Redux::ChannelCategory>] array of channel categories
+      def channel_categories
+        build :channel_categories, :using => data_for(:channel_categories)
+      end
+
+      # Logout of redux, invalidates your token. After calling this you cannot
+      # make any further requests with this client
+      # @return [nil]
+      def logout
+        data_for(:logout)
+        return nil
+      end
+
+      # Return all programmes for the schedule date, everything from 0600 for
+      # 24 hours afterwards. May make multiple requests to backend to retreive
+      # all the data
+      #
+      # @param [Date,DateTime,Time] date query this schedule date
+      # @param [String,Array<String>,Channel,Array<Channel>,nil] channel
+      #   optionally limit schedule query to one or an array of channels
+      # @return [Array<BBC::Redux::Asset>] the list of assets broadcast on date
+      def schedule(date, channels = nil)
+        query   = {
+          :date     => date,
+          :channels => channels,
+          :offset   => 0,
+          :limit    => 100,
+        }
+
+        results = search(query)
+
+        assets  = [ ]
+
+        while true do
+
+          assets.concat(results.assets)
+
+          if results.has_more?
+            next_query = results.query.merge({
+              :offset => results.query[:offset] + 100
+            })
+
+            results = self.search(next_query)
+          else
+            break
+          end
+        end
+
+        assets.sort { |a,b| b.start - a.start }
+      end
+
+      # Perform a search of Redux Archive
+      #
+      # @param [Hash] params your search parameters
+      # @option params [String] :q free text query
+      # @option params [String] :name query on programme name
+      # @option params [String,Array<String>,Channel,Array<Channel>] :channel
+      #   query on channel, e.g. 'bbcone'. Can provide an array to search on
+      #   multiple channels.
+      # @option params [Integer] :limit number of results to return. Default 10
+      # @option params [Integer] :offset offset of the start of results
+      # @option params [Date,DateTime,Time] :before only return braodcasts
+      #   before date
+      # @option params [Date,DateTime,Time] :after only return braodcasts after
+      #   date
+      # @option params [Date,DateTime,Time] :date everything from 0600 on given
+      #   date for 24hrs
+      # @option params [Integer] :longer constraint on the duration, in seconds
+      # @option params [Integer] :shorter constraint on the duration, in seconds
+      # @option params [String] :programme_crid TV Anytime CRID
+      # @option params [String] :series_crid TV Anytime CRID
+      # @see BBC::Redux::SearchResults
+      # @return [BBC::Redux::SearchResults] search results
+      def search(params = {})
+
+        mapper = lambda do |val|
+          if val.class == Date || val.class == DateTime || val.class == Time
+            val.strftime('%Y-%m-%dT%H:%M:%S')
+          elsif val.class == Channel
+            val.name
+          else
+            val.to_s
+          end
+        end
+
+        new_params = params.map do |key, val|
+          if val.class == Array
+            [ key, val.map(&mapper) ]
+          else
+            [ key, mapper.call(val) ]
+          end
+        end
+
+        data = data_for(:search_results, Hash[new_params]).merge({
+          'query' => params
+        })
+
+        build :search_results, :using => data
+      end
+
+      # Fetch user object for current session
+      # @see BBC::Redux::User
+      # @return [BBC::Redux::User, nil] the user
+      def user
+        build :user, :using => data_for(:user)
+      end
+
+      private
+
+      # @private
+      def build(type, options)
+        data = options.fetch(:using)
+
+        case type
+        when :asset
+          Serializers::Asset.new(Asset.new).from_hash(data)
+        when :channels
+          Serializers::Channels.new([]).from_hash(data)
+        when :channel_categories
+          Serializers::ChannelCategories.new([]).from_hash(data)
+        when :search_results
+          Serializers::SearchResults.new(SearchResults.new).from_hash(data)
+        when :user
+          Serializers::User.new(User.new).from_hash(data)
+        end
+      end
+
+      # @private
+      def url_for(action)
+        case action
+        when :asset
+          host + '/asset/details'
+        when :channels
+          host + '/asset/channel/available'
+        when :channel_categories
+          host + '/asset/channel/categories'
+        when :login
+          host + '/user/login'
+        when :logout
+          host + '/user/logout'
+        when :search_results
+          host + '/asset/search'
+        when :user
+          host + '/user/details'
+        end
+      end
+
+      # @private
+      def data_for(action, params = {})
+        url  = url_for action
+
+        # Patch typhoeus / ethon's handling of array params, essentially
+        # turn this /?key[0]=1&key[1]=2&key[2]=3 into this
+        # /?key=1&key=2&key=3
+
+        arrays = params.select { |_,v| v.class == Array }
+
+        unless arrays.empty?
+          url += '?' unless url =~ /\?$/
+
+          arrays.each do |key, values|
+            url += values.map { |v| "#{key}=#{v}" }.join('&')
+          end
+        end
+
+        params = params.select { |_,v| v.class != Array }
+
+        resp = http.post(url, {
+          :body           => params.merge(:token => token),
+          :followlocation => true,
+        })
+
+        case resp.code
+        when 200
+          JSON.parse(resp.body)
+        when 403
+          raise ForbiddenException.new("403 response for #{url}")
+        when 400..599
+          raise HttpException.new("#{resp.code} response for #{url}")
+        else
+          raise "Umm, not sure how to handle #{resp.code} for #{url}"
+        end
+
+      rescue JSON::ParserError => e
+        raise JsonParseException.new("Error parsing #{url}, #{e.message}")
+      end
+
+    end
+
+  end
+end

data/lib/bbc/redux/end_points.rb

@@ -0,0 +1,78 @@
+module BBC
+  module Redux
+
+    # @private
+    module EndPoints
+
+      HOST = 'https://i.bbcredux.com'
+
+      # Make dvb subs media file end point
+      # @param id    [String] asset identifier
+      # @param key   [String] string value of a valid access key
+      # @param fname [String] template for the file name
+      # @return [String] The end point
+      def self.dvbsubs(id, key, fname = nil)
+        HOST + "/asset/media/#{id}/#{key}/dvbsubs/#{(fname || '%s.xml') % id}"
+      end
+
+      # Make FLV media file end point
+      # @param id    [String] asset identifier
+      # @param key   [String] string value of a valid access key
+      # @param fname [String] template for the file name
+      # @return [String] The end point
+      def self.flv(id, key, fname = nil)
+        HOST + "/asset/media/#{id}/#{key}/Flash_v1.0/#{(fname || '%s.flv') % id}"
+      end
+
+      # Make mp3 media file end point
+      # @param id    [String] asset identifier
+      # @param key   [String] string value of a valid access key
+      # @param fname [String] template for the file name
+      # @return [String] The end point
+      def self.mp3(id, key, fname = nil)
+        HOST + "/asset/media/#{id}/#{key}/MP3_v1.0/#{(fname || '%s.mp3') % id}"
+      end
+
+      # Make h264_hi media file end point
+      # @param id    [String] asset identifier
+      # @param key   [String] string value of a valid access key
+      # @param fname [String] template for the file name
+      # @return [String] The end point
+      def self.h264_hi(id, key, fname = nil)
+        HOST + "/asset/media/#{id}/#{key}/h264_mp4_hi_v1.1/" \
+             + (fname || '%s-h264lg.mp4') % id
+      end
+
+      # Make h264_lo media file end point
+      # @param id    [String] asset identifier
+      # @param key   [String] string value of a valid access key
+      # @param fname [String] template for the file name
+      # @return [String] The end point
+      def self.h264_lo(id, key, fname = nil)
+        HOST + "/asset/media/#{id}/#{key}/h264_mp4_lo_v1.0/" \
+             + (fname || '%s-h264sm.mp4') % id
+      end
+
+      # Make ts media file end point
+      # @param id    [String] asset identifier
+      # @param key   [String] string value of a valid access key
+      # @param fname [String] template for the file name
+      # @return [String] The end point
+      def self.ts(id, key, fname = nil)
+        HOST + "/asset/media/#{id}/#{key}/ts/#{(fname || '%s.mpegts') % id}"
+      end
+
+      # Make stripped ts media file end point
+      # @param id    [String] asset identifier
+      # @param key   [String] string value of a valid access key
+      # @param fname [String] template for the file name
+      # @return [String] The end point
+      def self.ts_stripped(id, key, fname = nil)
+        HOST + "/asset/media/#{id}/#{key}/strip/" \
+             + (fname || '%s-stripped.mpegts') % id
+      end
+
+    end
+
+  end
+end

data/lib/bbc/redux/key.rb

@@ -0,0 +1,73 @@
+module BBC
+  module Redux
+
+    # Redux API Asset Key Object
+    #
+    # Each asset is served with an associated key that is needed to access
+    # it's associated media. Generally these keys have a lifetime of 24 hours
+    #
+    # @example Properties of the key object
+    #
+    #   key = redux_client.asset('5966413090093319525').key
+    #
+    #   key.expired?   #=> Boolean
+    #   key.expires_at #=> DateTime
+    #   key.live?      #=> Boolean
+    #   key.ttl        #=> Integer
+    #   key.value      #=> String
+    #
+    # @author Matt Haynes <matt.haynes@bbc.co.uk>
+    class Key
+
+      # @!attribute [r] expires_at
+      # @return [DateTime] the access key's expiry time
+      attr_reader :expires_at
+
+      # @!attribute [r] value
+      # @return [String] the access key's value
+      attr_reader :value
+
+      # @param value [String] the access keys value
+      def initialize(value)
+        @value      = value
+        @expires_at = Time.at( value.split('-')[1].to_i ).to_datetime
+      end
+
+      # @see Key#expired?
+      # @see Key#ttl
+      # @return [Boolean] true if ttl <= 0, false otherwise
+      def expired?
+        ttl <= 0
+      end
+
+      # @see Key#expired?
+      # @see Key#ttl
+      # @return [Boolean] true if ttl > 0, false otherwise
+      def live?
+        ttl > 0
+      end
+
+      # @return the key's value as a string
+      def to_s
+        value
+      end
+
+      # @see Key#expired?
+      # @see Key#expires_at
+      # @see Key#live?
+      # @return [Integer] key's Time To Live in seconds
+      def ttl
+        expires_at.to_time.to_i - Time.now.to_i
+      end
+
+      # @return [Boolean] true if other_key is a redux key with the same value
+      def ==(other_key)
+        self.class == other_key.class && self.value == other_key.value
+      end
+
+      alias :eql? :==
+
+    end
+
+  end
+end

data/lib/bbc/redux/media_url.rb

@@ -0,0 +1,123 @@
+require 'forwardable'
+require_relative 'end_points'
+require_relative 'key'
+
+module BBC
+  module Redux
+
+    # Redux API Asset URL Object
+    #
+    # Each asset is available as various transcodes using the url function.
+    # The urls are key based and therefore generally have a lifetime of 24 hours    #
+    #
+    # @example Properties of the url object
+    #
+    #   url = redux_client.asset('5966413090093319525').url(:mp3)
+    #
+    #   url.expired?   #=> Boolean
+    #   url.expires_at #=> DateTime
+    #   url.live?      #=> Boolean
+    #   url.ttl        #=> Integer
+    #   url.end_point  #=> String
+    #
+    # @example generate a URL with a different filename
+    #
+    #   url = redux_client.asset('5966413090093319525').mp3_url
+    #
+    #   url.end_point('myfile.mp3') #=> String
+    #
+    # @author Matt Haynes <matt.haynes@bbc.co.uk>
+    class MediaUrl
+
+      # Error raised when trying to initiate url with an unknown template type
+      class UnknownTemplateType < Exception; end
+
+      # Known URL templates, these are the only valid options for the
+      # type attribute of MediaUrl.initialize.
+      # @see MediaUrl#initialize
+      TEMPLATES = [
+        :dvbsubs,
+        :flv,
+        :h264_hi,
+        :h264_lo,
+        :mp3,
+        :ts,
+        :ts_stripped
+      ].freeze
+
+      # @!attribute [r] expires_at
+      # @return [DateTime] the access url's expiry time
+
+      # @!method expired?
+      # @see MediaUrl#expired?
+      # @see MediaUrl#ttl
+      # @return [Boolean] true if ttl <= 0, false otherwise
+
+      # @!method live?
+      # @see MediaUrl#expired?
+      # @see MediaUrl#ttl
+      # @return [Boolean] true if ttl > 0, false otherwise
+
+      # @!method ttl
+      # @see MediaUrl#expired?
+      # @see MediaUrl#live?
+      # @return [Integer] url's time to live in seconds
+
+      # @private
+      extend Forwardable
+
+      def_delegators :@key, :expired?, :expires_at, :live?, :ttl
+
+      # @!attribute [r] identifier
+      # @return [String] the url's indentifier
+      attr_reader :identifier
+
+      # @!attribute [r] type
+      # @see MediaUrl.TYPES
+      # @return [Symbol] the url's type
+      attr_reader :type
+
+      # @!attribute [r] key
+      # @return [BBC::Redux::Key] the url's key
+      attr_reader :key
+
+      # @param identifier [String] the disk reference or UUID of the asset
+      # @param type [Symbol] the transcode type, must be one of MediaUrl.TYPES
+      # @param key [BBC::Redux:Key] the key
+      # @raise [UnknownTranscodeType] if type parameter is unknown
+      # @see MediaUrl.TYPES
+      def initialize( identifier, type, key )
+
+        unless TEMPLATES.include?(type)
+          raise UnknownTemplateType.new("Unknown template type #{type}")
+        end
+
+        @identifier = identifier
+        @type       = type
+        @key        = key
+      end
+
+      # Generate the end point to retreive media file
+      #
+      # @param filename [String] an optional filename to specify on the end
+      #   point. This can also contain a "%s" template that will be populated
+      #   with the MediaUrl#identifier
+      # @return [String] The URL end point
+      def end_point(filename = nil)
+        EndPoints.send(type, identifier, key.value, filename)
+      end
+
+      alias :to_s :end_point
+
+      # @return [Boolean] true if other_url is a redux url with the same type,
+      #   identifier and key
+      def ==(other_url)
+        self.class == other_url.class && self.end_point == other_url.end_point
+      end
+
+      alias :eql? :==
+
+    end
+
+  end
+end

data/lib/bbc/redux/search_results.rb

@@ -0,0 +1,82 @@
+require 'virtus'
+require_relative 'asset'
+
+module BBC
+  module Redux
+
+    # Search results container
+    #
+    # @example Properties of search results
+    #
+    #   results = redux_client.search(:name => 'Pingu')
+    #
+    #   results.created_at     #=> DateTime
+    #   results.query          #=> Hash
+    #   results.query_time     #=> Float
+    #   results.assets         #=> Array<BBC::Redux::Asset>
+    #   results.total          #=> Integer
+    #   results.total_returned #=> Integer
+    #   results.has_more?      #=> Boolean
+    #
+    # @example Iterating all search results
+    #
+    #   results = redux_client.search(:name => 'Pingu', :offset => 0)
+    #
+    #   while true do
+    #     results.assets.each do |asset|
+    #       puts asset.name
+    #     end
+    #
+    #     if results.has_more?
+    #       next_query = results.query.merge({
+    #         :offset => results.query[:offset] + 10
+    #       })
+    #
+    #       results = redux_client.search(next_query)
+    #     else
+    #       break
+    #     end
+    #   end
+    #
+    class SearchResults
+
+      include Virtus.value_object
+
+      # @!attribute [r] created_at
+      # @return [DateTime] date and time results were retrieved
+      attribute :created_at, DateTime
+
+      # @!attribute [r] query
+      # @return [Hash] original parameters used in this query
+      attribute :query, Hash
+
+      # @attribute [r] query_time
+      # @return [Float] query time in seconds
+      attribute :query_time, Float
+
+      # @!attribute [r] assets
+      # @return [Array<BBC::Redux::Asset>] assets returned in this query
+      attribute :assets, Array[Asset]
+
+      # @!attribute [r] offset
+      # @return [Integer] offset of this set of results
+      attribute :offset, Integer
+
+      # @!attribute [r] total
+      # @return [Integer] total number of results
+      attribute :total, Integer
+
+      # @!attribute [r] total_returned
+      # @return [Integer] total number of results returned in this query
+      attribute :total_returned, Integer
+
+      # @return [Boolean] true if there are more results available than
+      #   returned in this query
+      def has_more?
+        (offset + total_returned) < total
+      end
+
+    end
+
+  end
+end