pomade 0.2.0 → 0.2.1

data/lib/pomade.rb

@@ -1,2 +1,8 @@
-require "pomade/version"
-require "pomade/publisher"
+require 'pomade/version'
+require 'pomade/exceptions'
+require 'pomade/publisher'
+
+##
+# A ruby library for Pomegranate.
+module Pomade
+end

data/lib/pomade/exceptions.rb

@@ -0,0 +1,19 @@
+module Pomade
+  # Errors thrown from Pomegranate
+  class ResponseError < StandardError; end
+
+  # If an asset's keys do not match up
+  class InvalidAssetKeys < StandardError; end
+
+  # If an asset's type is invalid
+  class InvalidAssetType < StandardError; end
+
+  # If a URL's response is not OK
+  class BadAssetValueURL < StandardError; end
+
+  # If an :image asset's value is not a valid URL
+  class InvalidImageValue < StandardError; end
+
+  # If an :video asset's value is not a valid URL
+  class InvalidVideoValue < StandardError; end
+end

data/lib/pomade/publisher.rb

@@ -3,35 +3,30 @@ require "ntlm/http"
 require "nokogiri"
 
 module Pomade
+  ##
+  # Handles all interactions to Pomegranate.
   class Publisher
-    # Public: Creates a new instance of Publisher that pushes records to
-    # Pomegranate.
+    ##
+    # Creates a new instance of +Publisher+ that pushes records to Pomegranate.
     # 
-    # Parameters: 
-    #
-    #   subdomain - [string] The subdomain for the Pomegranate instance that 
-    #               you'd like to connect to.
-    #   username  - [string] The username used for connecting to your instance.
-    #   password  - [string] The password used for connecting to your instance.
-    #   client_id - [string] Your client ID.
-    #   opts      - [hash] (optional) Additional options.
-    # 
-    #   Available options are:
-    #   host        - [string] The host (domain name) that Pomegranate lives on.
-    #   pathname    - [string] The path that is used for interacting with
-    #                 Pomegranate.
-    #   time_format - [string] (strftime) change the layout of the timestamp
-    #   domain      - [string] NTLM login domain.
-    #   debug       - [boolean] Turns on debug mode. This will print out
-    #                 any activity.
-    # 
-    # Returns:
+    # == Parameters
     # 
-    #   Returns an instance of Pomade::Publisher
+    # * *subdomain* _(string)_ - The subdomain for the Pomegranate instance that you'd like to connect to.
+    # * *username* _(string)_ - The username used for connecting to your isntance.
+    # * *password* _(string)_ - The password used for connecting to your isntance.
+    # * *client_id* _(string)_ - Your client ID.
+    # * *opts* _(hash, optional)_ - Additional options. Available options are:
+    #   * *:host* _(string)_ - The host (domain name) that your Pomegranate instance lives on.
+    #   * *:pathname* _(string)_ - The path that is used for interacting with assets.
+    #   * *:time_format* _(strftime)_ - Change the layout of the timestamp that is posted to your instance.
+    #   * *:domain* _(string)_ - NTLM login domain.
     # 
-    # Example:
+    # == Returns
+    # An instance of +Pomade::Publisher+
     # 
-    #   @pom = Pom.new('my-subdomain', 'myusername', 'mypassword', 'XX')
+    # == Example
+    #
+    #   @pom = Pomade::Publisher.new('my-subdomain', 'myusername', 'mypassword', 'XX')
     def initialize(subdomain, username, password, client_id, opts = {})
       @subdomain = subdomain
       @username = username
@@ -44,42 +39,64 @@ module Pomade
       @options[:pathname] = opts[:pathname] || '/p/p.svc/Assets/'
       @options[:time_format] = opts[:time_format] || "%Y-%m-%dT%H:%M:%SZ"
       @options[:domain] = opts[:domain] || nil
-      @options[:debug] = opts[:debug] || false
     end
 
-    # Public: Publishes an array of assets to Pomegranate
+    ##
+    # Publishes an array of assets to Pomegranate and returns the results in a +hash+.
     # 
-    # Parameters:
+    # == Parameters
     # 
-    #   assets - [array] A collection of assets. Each item consits of a hash with
-    #            three keys: { target: "", type: "", value: "" }
+    # * *assets* _(array)_ - A collection of assets. Each item consists of a hash with three keys: +:target+, +:type+ and +:value+. The values for keys +:target+ and +:value+ are both strings while the +:type+ key's value is a symbol. Available values are:
+    #   * +:image+ -- An +IMAGE+ type asset
+    #   * +:video+ -- A +VIDEO+ type asset
+    #   * +:text+ -- A +TEXT+ type asset
     # 
-    # Returns:
+    # == Returns
     # 
-    #   A hash containing two keys: record_id and assets.
+    # A +hash+ containing two keys: +record_id+ and +assets+.
     # 
-    # Example:
+    # == Example
     # 
     #   records = [
-    #     { target: "XX~USERNAME", type: "TEXT", value: "jakebellacera"},
-    #     { target: "XX~AVATAR", type: "IMAGE", value: "http://www.gravatar.com/avatar/98363013aa1237798130bc0fd2c4159d.png"}
+    #     { target: "XX~username", type: :text, value: "jakebellacera"},
+    #     { target: "XX~avatar", type: :image, value: "http://www.gravatar.com/avatar/98363013aa1237798130bc0fd2c4159d.png"}
     #   ]
+    #   
     #   @pom.publish(records)
-    #   #=> {
-    #         record_id: "XX-91c8071a-1201-4f99-bc9d-f8d53a947dc1",
-    #         assets: [
-    #           {"AssetID"=>"9a24c8e2-1066-42fb-be1c-697c5ead476d", "AssetData"=>"jakebellacera", "AssetType"=>"TEXT", "Target"=>"NS~USERNAME", "Client"=>"XX", "Status"=>"APPROVED", "AssetMeta"=>"", "AssetRecordID"=>"XX-91c8071a-1201-4f99-bc9d-f8d53a947dc1"},
-    #           {"AssetID"=>"9a24c8e2-1066-42fb-be1c-697c5ead476d", "AssetData"=>"http://www.gravatar.com/avatar/98363013aa1237798130bc0fd2c4159d.png", "AssetType"=>"IMAGE", "Target"=>"XX~Avatar", "Client"=>"XX", "Status"=>"APPROVED", "AssetMeta"=>"", "AssetRecordID"=>"XX-91c8071a-1201-4f99-bc9d-f8d53a947dc1"}
-    #         ]
+    #   # =>
+    #   {
+    #     record_id: "XX-91c8071a-1201-4f99-bc9d-f8d53a947dc1",
+    #     assets: [
+    #       {
+    #         "AssetID" => "9a24c8e2-1066-42fb-be1c-697c5ead476d",
+    #         "AssetData" => "jakebellacera",
+    #         "AssetType" => "TEXT",
+    #         "Target" => "XX~username",
+    #         "Client" => "XX",
+    #         "Status" => "APPROVED",
+    #         "AssetMeta" => "",
+    #         "AssetRecordID" => "XX-91c8071a-1201-4f99-bc9d-f8d53a947dc1"
+    #       },
+    #       {
+    #         "AssetID" => "9a24c8e2-1066-42fb-be1c-697c5ead476d",
+    #         "AssetData" => "http://www.gravatar.com/avatar/98363013aa1237798130bc0fd2c4159d.png",
+    #         "AssetType" => "IMAGE",
+    #         "Target" => "XX~avatar",
+    #         "Client" => "XX",
+    #         "Status" => "APPROVED",
+    #         "AssetMeta" => "",
+    #         "AssetRecordID" => "XX-91c8071a-1201-4f99-bc9d-f8d53a947dc1"
     #       }
+    #     ]
+    #   }
     def publish(assets)
-      puts "Available options: #{@options}" if @options[:debug]
-      @time = Time.now.strftime(@options[:time_format])
       @record_id = generate_record_id
+      @time = Time.now.strftime(@options[:time_format])
 
+      # Build our XMLs
       xmls = []
-      assets.each do |r|
-        xmls << build_xml(@record_id, r[:target], r[:type].upcase, r[:value])
+      validate(assets).each do |r|
+        xmls << build_xml(r[:target], r[:type].to_s.upcase, r[:value])
       end
 
       return {
@@ -88,41 +105,90 @@ module Pomade
       }
     end
 
-    # Public: Generates a record ID
-    #
-    # Parameters:
+    ##
+    # Validates an array of assets.
     # 
-    #   None
+    # == Parameters
     #
-    # Returns:
+    # * *assets* _(array)_ - A collection of assets. Each item consists of a hash with three keys: +:target+, +:type+ and +:value+. The values for keys +:target+ and +:value+ are both strings while the +:type+ key's value is a symbol. Available values are:
+    #   * +:image+ -- An +IMAGE+ type asset
+    #   * +:video+ -- A +VIDEO+ type asset
+    #   * +:text+ -- A +TEXT+ type asset
+    #
+    # == Returns
+    # 
+    # The +array+ of assets.
     # 
-    #   Returns a string containing the client_id with a UUID appended to it.
+    # == Example
+    # 
+    #   records = [
+    #     { target: "XX~USERNAME", type: :text, value: "jakebellacera"},
+    #     { target: "XX~AVATAR", type: :image, value: "http://www.gravatar.com/avatar/98363013aa1237798130bc0fd2c4159d.png"}
+    #   ]
+    #   
+    #   @pom.validate(records)
+    #   # =>
+    #   [
+    #     { target: "XX~USERNAME", type: :text, value: "jakebellacera"},
+    #     { target: "XX~AVATAR", type: :image, value: "http://www.gravatar.com/avatar/98363013aa1237798130bc0fd2c4159d.png"}
+    #   ]
+    def validate(assets)
+      available_keys = [:target, :type, :value].sort
+
+      assets.each do |a|
+        raise InvalidAssetKeys, "Each asset should only contain the keys: :target, :type, and :value." unless (a.keys & available_keys).sort == available_keys
+        raise InvalidAssetType, "Invalid asset type. Available choices are: :text, :image and :video." unless [:text, :image, :video].include?(a[:type])
+        test(a)
+      end
+    end
+
+    private
+
+    ##
+    # Generates a +SecureRandom.uuid+ (GUID) with the +client_id+ appended to it.
     def generate_record_id
       @client_id + '-' + SecureRandom.uuid
     end
 
-    private
+    ##
+    # Tests to see if an asset's +:value+ is correct in correlation to its +:type+.
+    def test(asset)
+      # If the value is a URL...
+      if (asset[:type] == :image || asset[:type] == :video) && url?(asset[:value])
+        raise BadAssetValueURL, "Please make sure your asset's value is a valid, working URL." unless Net::HTTP.get_response(URI(asset[:value])).code.to_i == 200
+      else
+        # Since the value was not a URL, we should raise an error for any IMAGE and VIDEO types.
+        raise BadImageValue, "assets with an :image type should have an image URL as the value." if asset[:type] == :image
+        raise BadVideoValue, "assets with a :video type should have a video URL as the value." if asset[:type] == :video
+      end
+    end
 
+    ##
+    # Posts an XML to the Pomegranate instance and handles the response.
+    #
+    # *Note:* This method will fail if any requests are rejected.
+    #
+    # == Parameters
+    # 
+    # * *body* _(string, XML)_ - A Pomegranate XML asset
+    #
+    # == Returns
+    # 
+    # An +array+ of comiled Pomegranate assets
     def post(data)
       response_data = []
       data.each do |xml|
-        puts xml if @options[:debug]
-
         req = send_request(xml)
 
-        if req[:code] == "201"
-          puts "===> SUCCESS!" if @options[:debug]
+        if req[:code].to_i.between?(200, 201)
           response_data << req[:data]
         else
           if req[:code] == "401"
-            # TODO: Tell user that we couldn't authenticate
-            puts "===> ERROR! Authentication" if @options[:debug]
+            raise ResponseError, "Could not authenticate with the Pomegranate API. Ensure that your credentials are correct."
           elsif req[:code] == "400"
-            # TODO: Tell the user there was a formatting error
-            puts "===> ERROR! Formatting" if @options[:debug]
+            raise ResponseError, "Bad asset value formatting. Please reformat and try again."
           else
-            # TODO: Tell the user an unknown error has occured
-            puts "===> ERROR Unknown" if @options[:debug]
+            raise StandardError, "An unknown error has occured."
           end
           response_data = false
           break
@@ -132,12 +198,17 @@ module Pomade
       response_data
     end
 
+    ##
+    # Sends a request to Pomegranate
+    #
+    # == Parameters
+    # 
+    # * *body* _(string, XML)_ - A Pomegranate XML asset
     def send_request(body)
       status = false
       data = false
       code = ""
 
-      puts "Initializing request for #{@subdomain + '.' + @options[:host]}" if @options[:debug]
       Net::HTTP.start("#{@subdomain}.#{@options[:host]}", 80) do |http|
         req = Net::HTTP::Post.new(@options[:pathname])
 
@@ -147,7 +218,6 @@ module Pomade
         req.ntlm_auth(@username, @options[:domain], @password)
 
         response = http.request(req)
-        puts response.inspect if @options[:debug]
 
         code = response.code
 
@@ -161,7 +231,9 @@ module Pomade
       {:code => code, :data => data}
     end
 
-    def build_xml(record_id, target, type, value)
+    ##
+    # Builds a Pomegranate asset XML file
+    def build_xml(target, type, value)
       <<-EOF.gsub(/^ {8}/, '')
         <?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>
         <entry
@@ -177,10 +249,10 @@ module Pomade
           <content type="application/xml">
             <m:properties>
               <d:AssetID>--</d:AssetID>
-              <d:AssetData>#{value}</d:AssetData>
+              <d:AssetData>#{type === "TEXT" ? escape_xml(value) : value}</d:AssetData>
               <d:AssetType>#{type}</d:AssetType>
               <d:AssetMeta></d:AssetMeta>
-              <d:AssetRecordID>#{record_id}</d:AssetRecordID>
+              <d:AssetRecordID>#{@record_id}</d:AssetRecordID>
               <d:Target>#{target}</d:Target>
               <d:Client>#{@client_id}</d:Client>
               <d:Status>APPROVED</d:Status>
@@ -190,6 +262,20 @@ module Pomade
       EOF
     end
 
+    ##
+    # Escapes any illegal XML characters
+    def escape_xml(string)
+      string.gsub!("&", "&amp;")
+      string.gsub!("<", "&lt;")
+      string.gsub!(">", "&gt;")
+      string.gsub!("'", "&apos;")
+      string.gsub!("\"", "&quot;")
+
+      return string
+    end
+
+    ##
+    # Parses XMLs and returns a hash
     def parse_xml(xml)
       parsed_xml = Nokogiri::XML(xml.gsub(/\n|\r|  /, ""))
       data = {}
@@ -198,5 +284,18 @@ module Pomade
       end
       data
     end
+
+    ##
+    # Tests if a string is a URL
+    def url?(string)
+      begin
+        uri = URI.parse(string)
+        %w( http https ).include?(uri.scheme)
+      rescue URI::BadURIError
+        false
+      rescue URI::InvalidURIError
+        false
+      end
+    end
   end
 end

data/lib/pomade/version.rb

@@ -1,3 +1,3 @@
 module Pomade
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/readme.md

@@ -33,51 +33,64 @@ These are the available options and their defaults.
     host:           'timessquare2.com',     # [string] The host (domain name) that Pomegranate lives on.
     pathname:       '/p/p.svc/Assets/',     # [string] The path that is used for interacting with Pomegranate.
     time_format:    "%Y-%m-%dT%H:%M:%SZ",   # [string] (strftime) change the layout of the timestamp.
-    login_domain:   nil,                    # [string] NTLM login domain.
-    debug:          false                   # [boolean] Turns on debug mode. This will print out any activity.
+    login_domain:   nil                     # [string] NTLM login domain.
 }
 ```
 
 ### Usage
 
-To publish assets to Pomegranate, simply create a new Publisher instance.
+To publish assets to Pomegranate, simply create a new `Pomade::Publisher` instance.
 
 ```ruby
 @pom = Pomade::Publisher.new('my-subdomain', 'myusername', 'mypassword', 'XX')
 ```
 
-Next, you'll want to push your assets to Pomegranate. You can do this by building an array of hashes. Each item in the array represents a single asset and they each have three keys: **target**, **type** and **value**. You'll pass this array into the `publisher#push` method.
+Next, you'll want to push your assets to Pomegranate. You can do this by building an array of hashes. Each item in the array represents a single asset and they each have three keys: **:target**, **:type** and **:value**. You'll pass this array into the `publish` method.
 
 ```ruby
 assets = [
-    { target: "XX~USERNAME", type: "TEXT", value: "jakebellacera"},
-    { target: "XX~AVATAR", type: "IMAGE", value: "http://www.gravatar.com/avatar/98363013aa1237798130bc0fd2c4159d.png"}
+  { target: "XX~username", type: :text, value: "jakebellacera"},
+  { target: "XX~avatar", type: :image, value: "http://www.gravatar.com/avatar/98363013aa1237798130bc0fd2c4159d.png"}
 ]
 
 record = @pom.publish(assets)
 ```
 
-The `Publisher#publish` method will return a **record**. A record is a hash with two keys: **record_id** and **assets**. The record_id is a randomly generated UUID string with your client_id prepended to it while the assets array is the posted assets. If assets is false, then the records failed to push to Pomegranate.
+The `publish` method will return a **record**. A record is a hash with two keys: **:record_id** and **:assets**. The `:record_id` is a randomly generated UUID string with your client_id prepended to it while the `:assets` array is the posted assets.
 
 ```ruby
 puts record
-#=> {
-      record_id: "XX-91c8071a-1201-4f99-bc9d-f8d53a947dc1",
-      assets: [
-        {"AssetID"=>"9a24c8e2-1066-42fb-be1c-697c5ead476d", "AssetData"=>"jakebellacera", "AssetType"=>"TEXT", "Target"=>"NS~USERNAME", "Client"=>"XX", "Status"=>"APPROVED", "AssetMeta"=>"", "AssetRecordID"=>"XX-91c8071a-1201-4f99-bc9d-f8d53a947dc1"},
-        {"AssetID"=>"9a24c8e2-1066-42fb-be1c-697c5ead476d", "AssetData"=>"http://www.gravatar.com/avatar/98363013aa1237798130bc0fd2c4159d.png", "AssetType"=>"IMAGE", "Target"=>"XX~Avatar", "Client"=>"XX", "Status"=>"APPROVED", "AssetMeta"=>"", "AssetRecordID"=>"XX-91c8071a-1201-4f99-bc9d-f8d53a947dc1"}
-      ]
+#=>
+{
+  record_id: "XX-91c8071a-1201-4f99-bc9d-f8d53a947dc1",
+  assets: [
+    {
+      "AssetID" => "9a24c8e2-1066-42fb-be1c-697c5ead476d",
+      "AssetData" => "jakebellacera",
+      "AssetType" => "TEXT",
+      "Target" => "XX~username",
+      "Client" => "XX",
+      "Status" => "APPROVED",
+      "AssetMeta" => "",
+      "AssetRecordID" => "XX-91c8071a-1201-4f99-bc9d-f8d53a947dc1"
+    },
+    {
+      "AssetID" => "9a24c8e2-1066-42fb-be1c-697c5ead476d",
+      "AssetData" => "http://www.gravatar.com/avatar/98363013aa1237798130bc0fd2c4159d.png",
+      "AssetType" => "IMAGE",
+      "Target" => "XX~avatar",
+      "Client" => "XX",
+      "Status" => "APPROVED",
+      "AssetMeta" => "",
+      "AssetRecordID" => "XX-91c8071a-1201-4f99-bc9d-f8d53a947dc1"
     }
+  ]
+}
 ```
 
-#### Debugging
-
-Sometimes Pomegranate will not be able to accept your request. If you're getting a 400 error, it's most likely a formatting issue. Since the errors returned by Pomegranate are not very verbose, it's best to run through a simple checklist instead:
+#### Validation
 
-* Ensure that your login info is correct. You can test in your browser by logging in via HTTPS at `<subdomain>.timessquare2.com`. If you'd like to use cURL or something else, connect via NTLM.
-* Make sure that the targets and types for each asset are correct. Targets will vary from client to client.
-* Try using the `debug` option.
-* If all else fails, you can try submitting an [issue](https://github.com/jakebellacera/pomade/issues). Please be specific in your bug report.
+Once you attempt to publish your assets, `Publisher` will attempt to validate your assets. Most of the time it will work, as Publisher will check your URLS for :image and :video types and ensure that they resolve properly. This validation may not find everything and you'll still get a bad response from Pomegranate, if that's the case, please [file a bug](http://github.com/jakebellacera/pomade/issues) with the steps you took to reproduce the problem.
 
 ## Contributing
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pomade
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-11 00:00:00.000000000 Z
+date: 2012-09-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-ntlm
@@ -55,6 +55,7 @@ files:
 - LICENSE.txt
 - Rakefile
 - lib/pomade.rb
+- lib/pomade/exceptions.rb
 - lib/pomade/publisher.rb
 - lib/pomade/version.rb
 - pomade.gemspec