vj-sdk 0.2.1

data/lib/videojuicer/resource/base.rb

@@ -0,0 +1,175 @@
+=begin rdoc
+
+  The Videojuicer::Resource module is a mixin that provides RESTful model features
+  to classes within the Videojuicer SDK. By including Videojuicer::Resource in a model
+  class, it will gain a series of class and instance methods that *approximate* the 
+  interface provided by a DataMapper or ActiveRecord-style object.
+
+
+
+=end
+
+module Videojuicer
+  module Resource
+      
+      include Videojuicer::Exceptions
+      include Videojuicer::Configurable
+      include Videojuicer::OAuth::ProxyFactory
+      include Videojuicer::Resource::Inferrable
+      include Videojuicer::Resource::PropertyRegistry
+      include Videojuicer::Resource::Types
+      include Videojuicer::Resource::Relationships::BelongsTo
+            
+      def self.included(base)
+        base.extend(ClassMethods)        
+        Inferrable.included(base)
+        PropertyRegistry.included(base)
+        Relationships::BelongsTo.included(base)
+      end
+          
+      # Determines if this instance is a new record. For the purposes of the SDK,
+      # this really means "does the item already have an ID?" - because if i reconstitute
+      # a known item without first retrieving it from the API, then saving that 
+      # object should push changes to the correct resource rather than creating a new
+      # object.
+      def new_record?
+        (id.to_i > 0)? false : true
+      end
+      
+      # Saves the record, creating it if is new and updating it if it is not.
+      # Returns TRUE on success and FALSE on fail.
+      def save 
+        proxy = proxy_for(config)
+        param_key = self.class.parameter_name
+        response =  if new_record?
+                      proxy.post(resource_path, param_key=>returnable_attributes)
+                    else
+                      proxy.put(resource_path, param_key=>returnable_attributes)
+                    end
+                    
+        # Parse and handle response
+        return validate_response(response)
+      end
+      
+      # Attempts to validate this object with the remote service. Returns TRUE on success,
+      # and returns FALSE on failure. Failure will also populate the #errors object on
+      # this instance.
+      def valid?
+        proxy = proxy_for(config)
+        param_key = self.class.parameter_name
+        response =  if new_record?
+                      proxy.post(resource_path(:validate, :nested=>false), param_key=>returnable_attributes)
+                    else
+                      proxy.put(resource_path(:validate, :nested=>false), param_key=>returnable_attributes)
+                    end
+                    
+        # Parse and handle response
+        return validate_response(response)
+      end
+      
+      
+      # The hash of errors on this object - keyed by attribute name, 
+      # with the error description as the value.
+      def errors=(arg); @errors = Videojuicer::Resource::Errors.new(arg); end
+      def errors; @errors ||= Videojuicer::Resource::Errors.new({}); end
+      def errors_on(key); errors.on(key); end
+      
+      # Takes a response from the API and performs the appropriate actions.
+      def validate_response(response)
+        body = response.body
+        attribs = (body.is_a?(Hash))? body : JSON.parse(body) rescue raise(JSON::ParserError, "Could not parse #{body}: \n\n #{body}")
+        attribs.each do |prop, value|
+          next if (prop == "id") and (value.to_i < 1)
+          self.send("#{prop}=", value) rescue next
+        end
+        
+        if e = attribs["errors"]
+          self.errors = e
+          return false
+        else
+          self.id = attribs["id"].to_i
+          self.errors = {}
+          return true
+        end
+      end
+      
+      # Updates the attributes and saves the record in one go.
+      def update_attributes(attrs)
+        self.attributes = attrs
+        return save
+      end
+      
+      # Makes a call to the API for the current attributes on this object.
+      # Overwrites the current instance attribute values.
+      def reload
+        raise NoResource, "Cannot load remote attributes for new records" if new_record?
+        response = proxy_for(config).get(resource_path(nil, :nested=>false))
+        return validate_response(response)
+      end
+      
+      # Attempts to delete this record. Will raise an exception if the record is new
+      # or if it has already been deleted.
+      def destroy
+        proxy_for(config).delete(resource_path)
+      end
+      
+      module ClassMethods
+        
+        # Finds all objects matching the criteria. Also allows filterable methods.
+        # Use :limit to throttle the amount of records returned.
+        # Use :offset to return all objects after a certain index. Combine with :limit for pagination.        
+        # You may specify comparators on attributes by giving them in the following forms:
+        # > "id"=>"9" #=> Returns only records with ID 9
+        # > "id.gt" => "9" #=> Returns only records with ID greater than 9
+        # > "id.lt" => "9" #=> Returns only records with ID less than 9
+        # > "id.gte" => "9" #=> Returns only records with ID greater than or equal to 9
+        # > "id.lte" => "9" #=> Returns only records with ID less than or equal to than 9
+        def all(options={})
+          # Get a proxy
+          options = (options.empty?)? {} : {parameter_name=>options} # FIXME this is a hacky workaround for singleton scope.
+          response = instance_proxy.get(base_path(:nested=>false), options)
+          op = JSON.parse(response.body)
+          
+          items = (op["items"] rescue op) # If "items" is on the returned object then this is a collection hash.
+          # Instantiate objects
+          items = items.collect do |attrs|
+            o = new; o.attributes = attrs
+            o
+          end
+          return (op.is_a?(Hash))? Videojuicer::Resource::Collection.new(items, op["count"], op["offset"], op["limit"]) : items
+        end
+        
+        def first(options={})
+          all(options.merge(:limit=>1)).first
+        end
+        
+        def create(attrs={})
+          o = new(attrs)
+          o.save
+          return o
+        end
+        
+        # Fetches an object given an ID. Straight forward.
+        def get(id)
+          o = new(:id=>id)
+          begin
+            o.reload 
+            o
+          rescue Videojuicer::Exceptions::NoResource
+            nil
+          end
+        end
+        
+        def destroy(id)
+          o = new(:id=>id)
+          o.destroy
+        end
+        
+        def instance_proxy
+          o = new
+          o.proxy_for(o.config)
+        end
+      end
+      
+  end
+end

data/lib/videojuicer/resource/collection.rb

@@ -0,0 +1,36 @@
+=begin rdoc
+  Videojuicer::Resource::Collection is an array extension returned by many common actions within
+  the Videojuicer SDK. Any request that returns paginated data, or a subset of your query results,
+  will return a Collection object containing the object subset, with some additional pagination
+  data.
+=end
+
+module Videojuicer
+  module Resource
+    class Collection < ::Array
+      
+      attr_accessor :limit
+      attr_accessor :offset
+      attr_accessor :total
+      
+      def initialize(objects, total, offset, limit)
+        clear
+        objects.each {|o| self << o }
+        self.total = total
+        self.offset = offset
+        self.limit = limit
+      end
+      
+      def page_count
+        return 1 if limit.nil?
+        (total.to_f/limit.to_f).ceil
+      end
+      
+      def page_number
+        return 1 if limit.nil?
+        (offset.to_f/limit.to_f).ceil
+      end
+      
+    end 
+  end
+end

data/lib/videojuicer/resource/embeddable.rb

@@ -0,0 +1,30 @@
+=begin rdoc
+  
+  A module that provides OEmbed functionality to any Videojuicer::Resource model.
+
+=end
+
+module Videojuicer
+  module Resource
+    module Embeddable
+      
+      OEMBED_ENDPOINT = "/oembed".freeze
+      
+      def oembed_payload(maxwidth, maxheight)
+        proxy = proxy_for(config)
+        result = proxy.get(OEMBED_ENDPOINT, :format=>"json", :url=>"#{proxy.host_stub}#{resource_path}?seed_name=#{seed_name}", :maxwidth=>maxwidth, :maxheight=>maxheight)
+        JSON.parse(result.body)
+      end
+      
+      def embed_size(maxwidth, maxheight)
+        p = oembed_payload(maxwidth, maxheight)
+        return p["width"], p["height"]
+      end
+      
+      def embed_code(maxwidth, maxheight)
+        oembed_payload(maxwidth, maxheight)["html"]
+      end
+      
+    end
+  end
+end

data/lib/videojuicer/resource/errors.rb

@@ -0,0 +1,17 @@
+module Videojuicer
+  module Resource
+    class Errors < Hash
+      
+      def initialize(error_hash)
+        self.merge!(error_hash)
+      end
+      
+      def on(key)
+        o = self[key.to_s]    
+        o = (o.is_a?(Array))? o.uniq : [o]
+        return (o.compact.empty?)? nil : o.compact
+      end
+      
+    end
+  end
+end

data/lib/videojuicer/resource/inferrable.rb

@@ -0,0 +1,141 @@
+=begin rdoc
+  =Inferred names
+
+  Inferrable contains methods used by Resources to automagically determine various
+  API parameters from the name of the including class.
+
+  E.g. 
+
+  class Videojuicer::Presentation
+    include Videojuicer::Resource # Inferrable is included by this line
+  end
+
+  Videojuicer::Presentation.resource_name #=> "presentation" (The base name)
+  Videojuicer::Presentation.parameter_name #=> "presentation" (The key used when crafting parameter keys e.g. presentation[title])
+  Videojuicer::Presentation.resource_path #=> "/presentations" (The base URI used to retrieve data related to objects of this tyle)
+  Videojuicer::Presentation.resource_path(id_of_presentation) #=> "/presentations/id_of_presentation.json" (The base URI used to retrieve data related to objects of this tyle)
+
+  m = Videojuicer::Presentation.new
+  m.resource_path #=> "/presentations" (The URI that will be used to )
+
+  m = Videojuicer::Presentation.first
+  m.id #=> 500, for example
+  m.resource_path #=> "/presentations/500.json"
+=end
+
+module Videojuicer
+  module Resource
+    module Inferrable
+  
+      def self.included(base)
+        base.extend(SingletonMethods)
+        base.send :include, InstanceMethods
+      end
+      
+      module InstanceMethods
+        # Returns the appropriate resource path for this object.
+        # If the object is a new record, then the root object type path
+        # will be given. If the object is not new (has an ID) then the
+        # specific ID will be used.
+        def resource_path(action=nil, route_options={})
+          route_options = {:id=>id}.merge(route_options) unless new_record?
+          r = self.class.resource_route(action, route_options)
+          self.class.compile_route(r, attributes)
+        end
+      end
+      
+      module SingletonMethods
+        
+        def compile_route(mask, properties={})
+          properties = properties.deep_stringify
+          result = []
+          mask.split("/").each do |member|
+            if member[0..0] == ":"
+              result << (properties[member.delete(":")])
+            else
+              result << member
+            end            
+          end
+          "#{result.join("/")}"
+        end
+        
+        # Nested resources are inferred from the class hierarchy:
+        # Something.parent_class #=> nil
+        # Something::Else.parent_class #=> Something        
+        # Monkeys::Are::Delicious
+        def containing_class
+          c = self.to_s.split("::"); c.pop
+          (c.any?)? Object.full_const_get(c.join("::")) : nil
+        end
+        
+        # The route fragment under which nested resources should be mapped.
+        def nesting_route
+          r = ["/#{plural_name}/#{nesting_route_key}"]
+          r = ([(self.containing_class.nesting_route rescue nil)] + r).compact.join("")
+        end
+        
+        # The key used by other models when referring to this one in resource routes. User.nesting_route_key == ":user_id"
+        def nesting_route_key
+          ":#{resource_name}_id"
+        end
+        
+        # Returns the lowercased, underscored version of the including class name.
+        # e.g. Videojuicer::ExampleModel.singular_name => "example_model"
+        def singular_name
+          @singular_name ||=  self.to_s.split("::").last.
+                              gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+                              gsub(/([a-z\d])([A-Z])/,'\1_\2').
+                              tr("-", "_").
+                              downcase.snake_case
+        end
+        
+        # Returns the plural version of the underscored singular name. This method,
+        # when compared directly and fairly to something like ActiveSupport's inflection
+        # module, is an idiot. You would be best to treat it as one.
+        def plural_name
+          if singular_name.match(/y$/)
+          	return singular_name.gsub(/y$/, "ies")
+          end          
+          # Fall back to the simplest rules
+          (singular_name.match(/s$/))? "#{singular_name}es" : "#{singular_name}s"
+        end
+        
+        # The name used to identify this resource to the API, and in responses from the API.
+        def resource_name
+          singular_name
+        end
+
+        # The name used to send parameters to the API. For instance, if a model named Cake has
+        # an attribute is_lie, and the parameter name of Cake is "cake", this attribute will be
+        # sent to the API as a parameter named cake[is_lie] with the appropriate value.
+        def parameter_name
+          singular_name
+        end
+
+        # The path to this class's resource given the desired action route.
+        # Returned as a mask with replaceable keys e.g. /fixed/fixed/:replaceme/fixed
+        def resource_route(action=nil, route_options={})
+          id = route_options.delete(:id)
+          action_stem = (id)? "/#{id}" : ""
+          action_stem += (action)? "/#{action}" : ""
+          action_stem += ".json" unless action_stem.empty?
+          "#{base_path(route_options)}#{action_stem}"
+        end
+        
+        # The root route for requests to the API. By default this is inferred from the plural name
+        # e.g. Videojuicer::Presentation uses /presentations as the resource_path.
+        def base_path(options={})
+  	      options = {
+  	      	:nested=>true
+  	      }.merge(options)
+          r = "/#{plural_name}"
+          r = "#{self.containing_class.nesting_route rescue nil}#{r}" if options[:nested]
+          return r
+        end
+        
+      end
+      
+      
+    end
+  end
+end

data/lib/videojuicer/resource/property_registry.rb

@@ -0,0 +1,145 @@
+=begin rdoc
+
+  = Property Registry
+  
+  This module allows model classes to register properties that have setter and getter methods,
+  and are earmarked to be included in calls between instances of those classes and the API.
+  
+  Properties are registered using a DataMapper-style syntax (ActiveRecord-style autodiscovery not
+  being possible).
+
+=end
+
+module Videojuicer
+  module Resource
+    module PropertyRegistry
+
+      def self.included(base)        
+        # Class-level inheritable reader
+        base.extend(SingletonMethods)
+        base.class_eval do
+          @attributes = {}
+          class << self
+            attr_accessor :attributes
+          end
+        end
+        base.property :id, Integer
+      end
+      
+      # Allow subclasses of each resource to get the attributes accessor
+      def self.inherited(subclass)
+        v = "@attributes"
+        subclass.instance_variable_set(v, instance_variable_get(v))
+      end
+
+      
+      def initialize(attrs={})
+        self.attributes = default_attributes
+        self.attributes = attrs
+      end
+      
+      def attributes
+        @attributes ||= {}
+        @attributes
+      end
+      
+      def attributes=(arg)
+        raise ArgumentError, "Attributes must be set as a Hash" unless arg.is_a?(Hash)
+        arg.each do |key, value|
+          self.send("#{key}=", value)
+        end
+      end
+      
+      def default_attributes
+        d = {}
+        self.class.attributes.each do |key, props|
+          d[key] = props[:default] ||  nil
+        end
+        return d
+      end
+      
+      def attr_get(key)
+        key = key.to_sym
+        attributes[key]
+      end
+      
+      def attr_set(key, value)
+        key = key.to_sym
+        attributes[key] = coerce_value(key, value)
+      end
+      
+      # Takes what is normally a string and coerces it into the correct object type for the 
+      # attribute's actual type.
+      def coerce_value(key, value)
+        return value unless value
+        klass = self.class.attributes[key][:class]
+        if value.is_a?(String) and value.any?
+          # In-built types
+          if klass.kind_of?(Videojuicer::Resource::Types::Base)
+            return klass.new(value).dump
+          end
+          
+          # Dates
+          if klass.respond_to?(:parse)
+            return klass.parse(value) rescue raise "Invalid date: #{value.inspect}"
+          end
+        elsif value.is_a? Hash and value.any?
+          if klass == DateTime
+            if value.is_a?(Hash)
+              year   = value[:year]
+              month  = value[:month]
+              day    = value[:day]
+              hour   = value[:hour] or "00"
+              minute = value[:minute] or "00"
+              value = klass.parse("#{year}-#{month}-#{day}T#{hour}:#{minute}:00+00:00")
+            else
+              raise ArgumentError, "Please supply a DateTime, Hash keyed w/ [:day, :month, :year, :hour, :minute] or a String that can be coerced into a date"
+            end
+          end
+        end
+        return value
+      end
+      
+      # Returns a hash of the attributes for this object, minus the
+      # private attributes that should not be included in the response.
+      def returnable_attributes
+        attrs = attributes.dup
+        self.class.attributes.select {|name, props| props[:writer] != :public}.each do |name, props|
+          attrs.delete name
+        end
+        attrs.delete(:id)
+        attrs
+      end
+      
+      module SingletonMethods
+        
+        # Registers an attribute using a datamapper-style syntax.
+        # Creates setter and getter methods
+        def property(prop_name, klass, options={})
+          # Can't raise twice.          
+          prop_name = prop_name.to_sym
+          raise ArgumentError, "Property #{prop_name} already registered." if self.attributes.include?(prop_name)
+          
+          options = {:class=>klass, :writer=>:public}.merge(options)
+          # Register with the class
+          self.attributes[prop_name] = options
+          # Create setter methods
+          define_method prop_name do
+            attr_get(prop_name)
+          end
+          
+          private if options[:writer] == :private
+          protected if options[:writer] == :protected
+          
+            define_method "#{prop_name}=" do |arg|
+              attr_set(prop_name, arg)
+            end
+          
+          public
+        end
+        
+      end
+      
+    end
+  end
+end

data/lib/videojuicer/resource/relationships/belongs_to.rb

@@ -0,0 +1,39 @@
+module Videojuicer
+  module Resource
+    module Relationships
+      module BelongsTo
+   
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+        
+        module ClassMethods
+          
+          def belongs_to(name, options={})
+            options = {
+              :class=>name.to_s.capitalize,
+              :foreign_key=>"#{name}_id"
+            }.merge(options)
+            
+            define_method name do
+              id = self.send(options[:foreign_key])
+              klass = (options[:class].is_a?(String))? Videojuicer.const_get(options[:class]) : options[:class]
+              return nil unless id
+              begin
+                return klass.get(id)
+              rescue Videojuicer::Exceptions::NoResource
+                return nil
+              end
+            end
+            
+            define_method "#{name}=" do |arg|
+              self.send("#{options[:foreign_key]}=", arg.id)
+            end
+          end
+          
+        end
+        
+      end
+    end
+  end
+end

data/lib/videojuicer/resource/types.rb

@@ -0,0 +1,28 @@
+module Videojuicer
+  module Resource
+    module Types
+      
+      class Base
+        def self.load(value)
+          return self.new(value)
+        end
+
+        def initialize(value)
+          @raw = value
+        end
+        
+        # Returns the source value
+        attr_reader :raw
+      end
+      
+      class Boolean < Base
+        # Boolean.new("1").dump #=> true
+        # Returns the coerced value
+        def dump
+          [1, "1", "true", "yes"].include?(raw)
+        end        
+      end
+    
+    end
+  end
+end

data/lib/videojuicer/session.rb

@@ -0,0 +1,74 @@
+=begin rdoc
+
+  A Videojuicer::Session object is the primary means of giving scope to your API calls.
+
+=end
+
+module Videojuicer
+  class Session
+        
+    include Videojuicer::Configurable
+    include Videojuicer::OAuth::ProxyFactory
+
+    def initialize(options={})
+      configure!(options)
+    end
+    
+    # Makes a call to the Videojuicer OAuth provider, requesting an unauthorised Request Token
+    # which will be returned as a Mash.
+    #
+    # See http://oauth.net/core/1.0/#auth_step1 for details.
+    #
+    # Each session will make only one request for an unauthorised request token. Further calls to
+    # get_request_token will return the same token and token secret.
+    #
+    # The Mash responds to the following methods:
+    # +oauth_token+ - The token key to be used as the oauth_token in calls using this token.
+    # +oauth_token_secret+ - The token secret to be used when signing requests using this token.
+    # +expires+ - The date and time at which the token will become invalid.
+    # +permissions+ - The permissions that you wish the token to have. Will be one of FooAttributeRegistry, write-user, read-master or write-master.
+    def get_request_token
+      # GET tokens.json
+      response = proxy_for(config).get("/oauth/tokens.json")
+      body = response.body
+      @request_token_response ||= JSON.parse(body)
+      @request_token_response["request_token"]
+    end
+    
+    # Generates and returns a fully-qualified signed URL that the user should be directed to
+    # by the consumer.
+    #
+    # See http://oauth.net/core/1.0/#auth_step2 for details.
+    #
+    # Can optionally be given a Mash previously obtained from a call to get_request_token, but in most
+    # cases this is not necessary - a request token will be requested and used automatically if one 
+    # is not supplied.
+    def authorize_url(token=get_request_token)
+      proxy_for(config.merge(:token=>token["oauth_token"], :token_secret=>token["oauth_token_secret"])).signed_url(:get, "/oauth/tokens/new", :oauth_callback=>token["oauth_callback"])
+    end
+    
+    # Once a user has completed the OAuth authorisation procedure at the provider end, you may call 
+    # exchange_request_token to make a request to the provider that will exchange your unauthorised
+    # request token for the corresponding authorised access token.
+    #
+    # See http://oauth.net/core/1.0/#auth_step3 for details.
+    #
+    # Returns a Mash that responds to the following methods:
+    # +oauth_token+ - The token key to be used as the oauth_token in calls using this token.
+    # +oauth_token_secret+ - The token secret to be used when signing requests using this token.
+    # +expires+ - The date and time at which the token will become invalid.
+    # +permissions+ - The permissions that you wish the token to have. Will be one of FooAttributeRegistry, write-user, read-master or write-master.
+    def exchange_request_token(token=get_request_token)
+      proxy = proxy_for(config.merge(:token=>token["oauth_token"], :token_secret=>token["oauth_token_secret"]))
+      response = proxy.get("/oauth/tokens.json")
+      t = response.body
+      Mash.new JSON.parse(t)["access_token"] rescue raise(JSON::ParserError, "could not parse: \n\n #{t}")
+    end
+    
+    def authorize!
+      # GET tokens.json with magic params
+      puts "not yet authorized"
+    end
+    
+  end
+end