helix 0.0.0.pre

data/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2012, Twistage
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of Twistage nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL Twistage BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,169 @@
+http://nestacms.com/docs/creating-content/markdown-cheat-sheet
+http://support.mashery.com/docs/customizing_your_portal/Markdown_Cheat_Sheet
+
+# Helix
+
+The Helix gem allows developers to easily connect to and manipulate the Twistage API.
+
+Documentation
+-------------
+
+You should find the documentation for your version of helix on [Rubygems](https://rubygems.org/gems/helix).
+
+Install
+--------
+
+```shell
+gem install helix
+```
+or add the following line to Gemfile:
+
+```ruby
+gem 'helix'
+```
+and run `bundle install` from your shell.
+
+Install From Repo
+-----------------
+Using sudo:
+```shell
+git clone git@github.com:Twistage/helix.git 
+gem build helix.gemspec  
+sudo gem i helix-*.gem
+```
+
+RVM or root support:
+```shell
+git clone git@github.com:Twistage/helix.git
+gem build helix.gemspec
+gem i helix-*.gem
+```
+
+Rebuilding the gem, use the first for sudo, the second for RVM or root:
+```shell
+rake reinstall_helix
+rake reinstall_helix_rvm
+```
+
+Using gem in a Gemfile  
+```shell
+gem 'helix', :git => git@github.com:Twistage/helix.git
+```
+
+
+
+Supported Ruby versions
+-----------------------
+
+1.9.3  
+1.9.2  
+
+How To
+------
+
+###Setup YAML
+```yaml
+site: 'http://service.twistage.com'
+user: 'my_account@twistage.com'
+password: 'password123'
+company: 'my_company'
+license_key: '141a86b5c4091
+```
+Load the YAML file as your config.
+```ruby
+Helix::Config.load("path/to/yaml.yml")
+```
+####Current CRUD methods supported by all models
+.create  
+.find  
+\#update  
+\#destroy  
+
+####Current models
+Videos, Images, Albums, Tracks, Playlists
+
+###Videos
+#####Required fields: title, description, library, company, and source.
+```ruby
+video = Helix::Video.create!( title:       'New Video', 
+                              description: 'A video of new things', 
+                              source:      'http://somesource.com/source.mp4'
+                              company:     'some_company',
+                              library:     'some_library')
+video.update({title: "New Title"})
+another_video = Helix::Video.find(some_guid)
+another_video.destroy
+```
+###Albums
+#####Required fields: title, library, company.
+```ruby
+album = Helix::Album.create!( title:       'New Album', 
+                              description: 'A album of new things', 
+                              source:      'http://somesource.com/source.mp4'
+                              company:     'some_company',
+                              library:     'some_library')
+#Update for album is not currently supported
+another_album = Helix::Album.find(some_guid)
+another_album.destroy
+```
+###Images
+#####Required fields: title, description, library, company, and source.
+```ruby
+image = Helix::Image.create!( title:       'New Image', 
+                              description: 'A image of new things', 
+                              source:      'http://somesource.com/source.jpg'
+                              company:     'some_company',
+                              library:     'some_library')
+image.update({title: "New Title"})
+another_image = Helix::Image.find(some_guid)
+another_image.destroy
+```
+###Tracks
+#####Required fields: title, description, library, company, and source.
+```ruby
+track = Helix::Track.create!( title:       'New Track', 
+                              description: 'A track of new things', 
+                              source:      'http://somesource.com/source.mp3'
+                              company:     'some_company',
+                              library:     'some_library')
+track.update({title: "New Title"})
+another_track = Helix::Track.find(some_guid)
+another_track.destroy
+```
+###Playlists
+#####Required fields: title, library, company.
+```ruby
+playlist = Helix::Playlist.create!( title:       'New Playlist', 
+                                    description: 'A playlist of new things', 
+                                    source:      'http://somesource.com/source.mp4'
+                                    company:     'some_company',
+                                    library:     'some_library')
+playlist.update({title: "New Title"})
+another_playlist = Helix::Playlist.find(some_guid)
+another_playlist.destroy
+```
+
+More Information
+----------------
+
+* [Rubygems](https://rubygems.org/gems/helix)
+* [Issues](https://github.com/twistage/helix/issues)
+
+Contributing
+------------
+
+How to contribute
+
+Credits
+-------
+
+Helix was written by Kevin Baird and Michael Wood.
+
+Helix is maintained and funded by [Twistage, inc](http://twistage.com)
+
+The names and logos for twistage are trademarks of twistage, inc.
+
+License
+-------
+
+Helix is Copyright © 2008-2012 Twistage, inc.

data/lib/helix/album.rb

@@ -0,0 +1,27 @@
+require 'helix/base'
+
+module Helix
+
+  class Album < Base
+
+    # The class name, to be used by supporting classes. Such as Config which uses
+    # this method as a way to build URLs.
+    #
+    #
+    # @example
+    #   Helix::Album.media_type_sym #=> :album
+    #
+    # @return [Symbol] Name of the class.
+    def self.media_type_sym; :album; end
+
+    # Currently update is unsupported for album.
+    #
+    # @param [Hash] opts an array can be passed in so it remains functionally similiar to other update calls.
+    # @return [Exception] "Albums Update is not currently supported."
+    def update(opts={})
+      raise "Albums Update is not currently supported."
+    end
+
+  end
+
+end

data/lib/helix/base.rb

@@ -0,0 +1,185 @@
+require 'rest_client'
+require 'json'
+require 'yaml'
+require 'crack'
+
+module Helix
+  class Base
+
+    unless defined?(self::METHODS_DELEGATED_TO_CLASS)
+      METHODS_DELEGATED_TO_CLASS = [ :guid_name, :media_type_sym, :plural_media_type ]
+    end
+
+    attr_accessor :attributes, :config
+
+    # Creates a new record via API and then returns an instance of that record.
+    #
+    # Example is using Video class since Video inherits from Base. This won't
+    # normally be called as Helix::Base.create
+    #
+    # @example
+    #   Helix::Video.create({title: "My new video"})
+    #
+    # @param [Hash] attributes a hash containing the attributes used in the create
+    # @return [Base] An instance of Helix::Base
+    def self.create(attributes={})
+      config    = Helix::Config.instance
+      #xml       = '<?xml version="1.0" encoding="UTF-8"?>
+      #              <add>
+      #                <list>
+      #                  <entry>
+      #                    <src>http://www.minhreigen.com/videos/play.mp4</src>
+      #                    <title>Summer camp dance</title>
+      #                    <description>This one is the best</description>
+      #                  </entry>
+      #                </list>
+      #              </add>'.gsub!(/\s{2,}|\n/, "")
+      url       = config.build_url(media_type:  plural_media_type,
+                                   format:      :xml)
+      response  = RestClient.post(url, attributes.merge(signature: config.signature(:update)))
+      attrs     = Crack::XML.parse(response)
+      self.new(attributes: attrs[media_type_sym.to_s], config: config)
+    end
+
+    # Finds and returns a record in instance form for a class, through
+    # guid lookup.
+    #
+    # @example
+    #   video_guid  = "8e0701c142ab1"
+    #   video       = Helix::Video.find(video_guid)
+    #
+    # @param [String] guid an id in guid form.
+    # @return [Base] An instance of Helix::Base
+    def self.find(guid)
+      config = Helix::Config.instance
+      item   = self.new(attributes: { guid_name => guid }, config: config)
+      item.load
+    end
+
+    # Fetches all accessible records, places them into instances, and returns
+    # them as an array.
+    #
+    # @example
+    #   Helix::Video.find_all(query: 'string_to_match') #=> [video1,video2]
+    #
+    # @param [Hash] opts a hash of options for parameters passed into the HTTP GET
+    # @return [Array] The array of instance objects for a class.
+    def self.find_all(opts)
+      data_sets = get_data_sets(opts)
+      return [] if data_sets.nil?
+      data_sets.map { |attrs| self.new(attributes: attrs) }
+    end
+
+    def self.get_data_sets(opts)
+      config       = Helix::Config.instance
+      url          = config.build_url(format: :json)
+      # We allow opts[:sig_type] for internal negative testing only.
+      raw_response = config.get_response(url, {sig_type: :view}.merge(opts))
+      data_sets    = raw_response[plural_media_type]
+    end
+
+    # Creates a string that associates to the class id.
+    #
+    # @example
+    #   Helix::Video.guid_name #=> "video_id"
+    #
+    # @return [String] The guid name for a specific class.
+    def self.guid_name
+      "#{self.media_type_sym}_id"
+    end
+
+    # Creates a string associated with a class name pluralized
+    #
+    # @example
+    #   Helix::Video.plural_media_type #=> "videos"
+    #
+    # @return [String] The class name pluralized
+    def self.plural_media_type
+      "#{self.media_type_sym}s"
+    end
+
+    METHODS_DELEGATED_TO_CLASS.each do |meth|
+      define_method(meth) { |*args| self.class.send(meth, *args) }
+    end
+
+    def initialize(opts)
+      @attributes = opts[:attributes]
+      @config     = opts[:config]
+    end
+
+    # Deletes the record of the Helix::Base instance.
+    #
+    # @example
+    #   video = Helix::Video.create({title: "Some Title"})
+    #   video.destroy
+    #
+    # @return [String] The response from the HTTP DELETE call.
+    def destroy
+      memo_cfg = config
+      url      = memo_cfg.build_url(format: :xml, guid: guid, media_type: plural_media_type)
+      RestClient.delete(url, params: {signature: memo_cfg.signature(:update)})
+    end
+
+    # Creates a string that associates to the class id.
+    #
+    # @example
+    #   video = Helix::Video.create({title: "My new title"})
+    #   video.guid #=> "9e0989v234sf4"
+    #
+    # @return [String] The guid for the class instance.
+    def guid
+      @attributes[guid_name]
+    end
+
+    # Loads in the record from a HTTP GET response.
+    #
+    # @param [Hash] opts a hash of attributes to update the instance with.
+    # @return [Base] Returns an instance of the class.
+    def load(opts={})
+      memo_cfg    = config
+      url         = memo_cfg.build_url(format: :json, guid: self.guid, media_type: plural_media_type)
+      # We allow opts[:sig_type] for internal negative testing only.
+      raw_attrs   = memo_cfg.get_response(url, {sig_type: :view}.merge(opts))
+      @attributes = massage_raw_attrs(raw_attrs)
+      self
+    end
+    alias_method :reload, :load
+
+    # Raises an error for missing method calls.
+    #
+    # @param [Symbol] method_sym The method attempting to be called.
+    # @return [String] An error for the method attempting to be called.
+    def method_missing(method_sym)
+      begin
+        @attributes[method_sym.to_s]
+      rescue
+        raise NoMethodError, "#{method_sym} is not recognized within #{self.class.to_s}'s @attributes"
+      end
+    end
+
+    # Updates instance and record with attributes passed in.
+    #
+    # @example
+    #   video = Helix::Video.find(video_guid)
+    #   video.update({title: "My new title"})
+    #
+    # @param [Hash] opts a hash of attributes to update the instance with.
+    # @return [Base] Returns an instance of the class after update.
+    def update(opts={})
+      memo_cfg = config
+      url      = memo_cfg.build_url(format: :xml, guid: guid, media_type: plural_media_type)
+      params   = {signature: memo_cfg.signature(:update)}.merge(media_type_sym => opts)
+      RestClient.put(url, params)
+      self
+    end
+
+    private
+
+    def massage_raw_attrs(raw_attrs)
+      # FIXME: Albums JSON output is embedded as the only member of an Array.
+      proper_hash = raw_attrs.respond_to?(:has_key?) && raw_attrs.has_key?(guid_name)
+      proper_hash ? raw_attrs : raw_attrs.first
+    end
+
+  end
+end

data/lib/helix/config.rb

@@ -0,0 +1,150 @@
+require 'helix/video'
+require 'helix/track'
+require 'helix/album'
+require 'helix/image'
+require 'singleton'
+
+module Helix
+
+  class Config
+
+    include Singleton
+
+    unless defined?(self::DEFAULT_FILENAME)
+      DEFAULT_FILENAME = './helix.yml'
+      SCOPES           = %w(reseller company library)
+      SIG_DURATION     = 1200 # in minutes
+      TIME_OFFSET      = 1000 * 60 # 1000 minutes, lower to give some margin of error
+      VALID_SIG_TYPES  = [ :ingest, :update, :view ]
+    end
+
+    attr_accessor :credentials
+
+    # Creates a singleton of itself, setting the config
+    # to a specified YAML file. If no file is specified the default
+    # helix.yml file is used.
+    #
+    # @example
+    #   Helix::Config.load("/some/path/my_yaml.yml")
+    #   video = Helix::Video.find("8e0701c142ab1") #Uses my_yaml.yml
+    #
+    # @param [String] yaml_file_location the yaml file used for config
+    # @return [Helix::Config] config returns singleton of Helix::Config
+    def self.load(yaml_file_location = DEFAULT_FILENAME)
+      config = self.instance
+      config.instance_variable_set(:@filename,    yaml_file_location)
+      config.instance_variable_set(:@credentials, YAML.load(File.open(yaml_file_location)))
+      config
+    end
+
+    # Creates additional URL stubbing that can be used in conjuction
+    # with the base_url to create RESTful URLs
+    #
+    # @param [String] base_url the base part of the URL to be used
+    # @param [Hash] opts a hash of options for building URL additions
+    # @return [String] The full RESTful URL string object
+    def add_sub_urls(base_url, opts)
+      guid, action = [:guid, :action].map { |sub| opts[sub] }
+      url   = "#{base_url}/#{opts[:media_type]}"
+      url  += "/#{guid}"   if guid
+      url  += "/#{action}" if action
+      "#{url}.#{opts[:format]}"
+    end
+
+    # Creates a full RESTful URL to be used for HTTP requests.
+    #
+    # @param [Hash] opts a hash of options for building URL
+    # @return [String] The full RESTful URL string object
+    def build_url(opts={})
+      opts[:format]     ||= :json
+      opts[:media_type] ||= :videos
+      base_url = get_base_url(opts)
+      url      = add_sub_urls(base_url, opts)
+    end
+
+    # Creates the base url with information collected from credentials.
+    #
+    # @param [Hash] opts a hash of options for building URL
+    # @return [String] The base RESTful URL string object
+    def get_base_url(opts)
+      creds     = credentials
+      base_url  = creds['site']
+      reseller, company, library = SCOPES.map { |scope| creds[scope] }
+      base_url += "/resellers/#{reseller}" if reseller
+      if company
+        base_url += "/companies/#{company}"
+        base_url += "/libraries/#{library}" if library
+      end
+      base_url
+    end
+
+    # Creates additional URL stubbing that can be used in conjuction
+    # with the base_url to create RESTful URLs
+    #
+    # @param [String] url the base part of the URL to be used
+    # @param [Hash] opts a hash of options for building URL additions
+    # @return [String] The full RESTful URL string object
+    def get_response(url, opts={})
+      sig_type    = opts.delete(:sig_type)
+      params      = opts.merge(signature: signature(sig_type, opts))
+      response    = RestClient.get(url, params: params)
+      JSON.parse(response)
+    end
+
+    # Fetches the signature for a specific license key.
+    #
+    # @param [Symbol] sig_type The type of signature required for calls.
+    # @return [String] The signature needed to pass around for calls.
+    def signature(sig_type, opts={})
+      prepare_signature_memoization
+      memo_sig = existing_sig_for(sig_type)
+      return memo_sig if memo_sig
+      unless VALID_SIG_TYPES.include?(sig_type)
+        raise ArgumentError, error_message_for(sig_type)
+      end
+
+      lk = license_key
+      @signature_expiration_for[lk][sig_type] = Time.now + TIME_OFFSET
+      @signature_for[lk][sig_type] = RestClient.get(url_for(sig_type, opts))
+    end
+
+    private
+
+    def error_message_for(sig_type)
+      "I don't understand '#{sig_type}'. Please give me one of :ingest, :update, or :view."
+    end
+
+    def existing_sig_for(sig_type)
+      return if sig_expired_for?(sig_type)
+      @signature_for[license_key][sig_type]
+    end
+
+    def license_key
+      @credentials['license_key']
+    end
+
+    def prepare_signature_memoization
+      lk = license_key
+      @signature_for                ||= {}
+      @signature_expiration_for     ||= {}
+      @signature_for[lk]            ||= {}
+      @signature_expiration_for[lk] ||= {}
+    end
+
+    def sig_expired_for?(sig_type)
+      expires_at = @signature_expiration_for[license_key][sig_type]
+      return true if expires_at.nil?
+      expires_at <= Time.now
+    end
+
+    def url_for(sig_type, opts={})
+      contributor, library_id = [:contributor, :library_id].map { |key| opts[key] }
+      url  = "#{credentials['site']}/api/#{sig_type}_key?licenseKey=#{credentials['license_key']}&duration=#{SIG_DURATION}"
+      url += "&contributor=#{contributor}"  if contributor
+      url += "&library_id=#{library_id}"    if library_id
+      url
+    end
+
+  end
+
+end

data/lib/helix/image.rb

@@ -0,0 +1,19 @@
+require 'helix/base'
+
+module Helix
+
+  class Image < Base
+
+    # The class name, to be used by supporting classes. Such as Config which uses
+    # this method as a way to build URLs.
+    #
+    #
+    # @example
+    #   Helix::Image.media_type_sym #=> :image
+    #
+    # @return [Symbol] Name of the class.
+    def self.media_type_sym; :image; end
+
+  end
+
+end