RubyGems - vuzitruby - Versions diffs - 1.0.0 - Mend

vuzitruby 1.0.0

Files changed (7) hide show

data/README ADDED Viewed

@@ -0,0 +1,101 @@
+= VuzitRuby - Vuzit Web Services library
+== INTRODUCTION
+This is a library that allows developers to directly access the Vuzit Web
+Service API through a simple Ruby script:
+http://vuzit.com/developer/documents_api
+Below is a basic upload example:
+  require "vuzitruby"
+  Vuzit::Service.public_key = 'YOUR_PUBLIC_API_KEY'
+  Vuzit::Service.private_key = 'YOUR_PRIVATE_API_KEY'
+  doc = Vuzit::Document.upload("c:/path/to/document.pdf")
+  puts "Document id: " + doc.id
+To get started all you need to do is download the code, sign up for a free
+account (https://ssl.vuzit.com/signup) and replace the public and
+private keys with the keys from your account.
+== SETUP
+The client library is a RubyGem called *vuzitruby*. To install, type:
+  sudo gem install vuzitruby
+== GETTING STARTED
+* Download the code - http://github.com/vuzit/vuzitruby/downloads
+* Sign up for a free Vuzit account - https://ssl.vuzit.com/signup
+* Code Examples - http://wiki.github.com/vuzit/vuzitruby/code-examples
+* Vuzit API Reference - http://doc.vuzit.com/vuzitruby
+== EXAMPLES
+Find Document Example - how to load a document:
+  require "vuzitruby"
+  Vuzit::Service.public_key = 'YOUR_PUBLIC_API_KEY'
+  Vuzit::Service.private_key = 'YOUR_PRIVATE_API_KEY'
+  doc = Vuzit::Document::find("DOCUMENT_ID")
+  puts "Document id: " + doc.id
+  puts "Document title: " + doc.title
+Delete (destroy) Document Example:
+  require "vuzitruby"
+  Vuzit::Service.public_key = 'YOUR_PUBLIC_API_KEY'
+  Vuzit::Service.private_key = 'YOUR_PRIVATE_API_KEY'
+  doc = Vuzit::Document::destroy("DOCUMENT_ID")
+Upload and View with the JavaScript API Example for a Rails RHTML file:
+  <%
+  require "vuzitruby"
+  require 'cgi'
+  Vuzit::Service.public_key = 'YOUR_PUBLIC_API_KEY'
+  Vuzit::Service.private_key = 'YOUR_PRIVATE_API_KEY'
+  doc = Vuzit::Document.upload("c:/path/to/document.pdf")
+  timestamp = Time.now
+  sig = Vuzit::Service.get_signature("show", doc.id, timestamp)
+  %>
+  <html>
+    <head>
+      <link href="http://vuzit.com/stylesheets/Vuzit-2.6.css" rel="Stylesheet" type="text/css" />
+      <script src="http://vuzit.com/javascripts/Vuzit-2.6.js" type="text/javascript"></script>
+      <script type="text/javascript">
+        // Called when the page is loaded.
+        function initialize()  {
+          vuzit.Base.PublicKeySet("<%= Vuzit::Service.public_key %>");
+          var options = {signature: '<%= CGI.escape(sig) %>',
+                         timestamp: '<%= timestamp %>', ssl: true}
+          var viewer = vuzit.Viewer.fromId("<%= doc.id %>", options);
+          viewer.display(document.getElementById("vuzit_viewer"), { zoom: 1 });
+        }
+      </script>
+    </head>
+    <body onload="initialize()">
+      <div id="vuzit_viewer" style="width: 650px; height: 500px;"></div>
+    </body>
+  </html>
+== LICENSE
+Released under the MIT license:
+http://www.opensource.org/licenses/mit-license.php
+This means you can use it in proprietary products. See LICENSE file.

data/Rakefile ADDED Viewed

@@ -0,0 +1,41 @@
+require 'rubygems'
+require 'spec/rake/spectask'
+spec = Gem::Specification.new do |s|
+  s.name = 'vuzitruby'
+  s.version = "1.0.0"
+  s.homepage = 'http://vuzit.com/'
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Brent Matzelle"]
+  s.date = %q{2009-3-30}
+  s.description = %q{This is a library for the Vuzit Web Services API.  For
+                     more information on the platform, visit
+                     http://vuzit.com/developer}
+  s.email = %q{support@vuzit.com}
+  s.extra_rdoc_files = ["README"]
+  s.files = ["README", "Rakefile", "lib/vuzitruby.rb",
+             "lib/vuzitruby/document.rb", "lib/vuzitruby/exception.rb",
+             "lib/vuzitruby/service.rb"]
+  s.has_rdoc = true
+  #s.rdoc_options = ["--main", "README"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{vuzitruby}
+  s.rubygems_version = %q{1.0.0}
+  s.summary = %q{Ruby client library for the Vuzit Web Services API}
+  s.extra_rdoc_files = ["README"]
+end
+namespace :github do
+  desc "Prepare for GitHub gem packaging"
+  task :prepare do
+    `rake debug_gem > vuzitruby.gemspec`
+  end
+end
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end

data/lib/vuzitruby/document.rb ADDED Viewed

@@ -0,0 +1,276 @@
+require 'rexml/document'
+require 'uri'
+require 'cgi'
+class Hash #:nodoc:all
+   # Taken from Rails, with appreciation to DHH
+   def stringify_keys
+     inject({}) do |options, (key, value)|
+       options[key.to_s] = value
+       options
+     end
+   end unless method_defined?(:stringify_keys)
+end
+module Vuzit
+  # Class for uploading, loading, and deleting documents using the Vuzit Web
+  # Service API: http://vuzit.com/developer/documents_api
+  #
+  # To use this class you need to {sign up}[http://vuzit.com/signup] for
+  # Vuzit first.
+  class Document
+    # The document ID
+    attr_accessor :id
+    # The document title
+    attr_accessor :title
+    # The document subject
+    attr_accessor :subject
+    # Number of pages of the document
+    attr_accessor :page_count
+    # Page width of the document in pixels
+    attr_accessor :page_width
+    # Page height of the document in pixels
+    attr_accessor :page_height
+    # File size of the original document bytes
+    attr_accessor :file_size
+    TRIES = 3 #:nodoc:
+    # Constructor.
+    def initialize #:nodoc:
+      # Set the defaults
+      @id = @title = @subject = nil
+      @page_count = @page_width = @page_height = @file_size = -1
+    end
+    # Deletes a document by the ID.  Returns true if it succeeded.  It throws
+    # a Vuzit::Exception on failure.  It returns _true_ on success.
+    #
+    # Example:
+    #
+    #  Vuzit::Service.public_key = 'YOUR_PUBLIC_API_KEY'
+    #  Vuzit::Service.private_key = 'YOUR_PRIVATE_API_KEY'
+    #
+    #  result = Vuzit::Document.destroy("DOCUMENT_ID")
+    def self.destroy(id)
+      timestamp = Time.now
+      sig = CGI.escape(Vuzit::Service::get_signature('destroy', id, timestamp))
+      # Create the connection
+      uri = URI.parse(Vuzit::Service.service_url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      query = "/documents/#{id}.xml?key=#{Vuzit::Service.public_key}" +
+              "&signature=#{sig}&timestamp=#{timestamp.to_i}"
+      request = Net::HTTP::Delete.new(query)
+      response = http.start { http.request(request) }
+      if response.code.to_i != 200
+        # Some type of error ocurred
+        begin
+          doc = REXML::Document.new(response.body)
+        rescue Exception => ex
+          raise Vuzit::Exception.new("XML error: #{ex.message}")
+        end
+        if doc.root != nil
+          code = doc.root.elements['code']
+          if code != nil
+            raise Vuzit::Exception.new(doc.root.elements['msg'].text, code.text.to_i);
+          end
+        end
+        # At this point we don't know what the error is
+        raise Vuzit::Exception.new("Unknown error occurred #{response.message}", response.code)
+      end
+      debug(response.code + " " + response.message + "\n")
+      return true
+    end
+    # Finds a document by the ID.  It throws a Vuzit::Exception on failure.
+    #
+    # Example:
+    #
+    #  Vuzit::Service.public_key = 'YOUR_PUBLIC_API_KEY'
+    #  Vuzit::Service.private_key = 'YOUR_PRIVATE_API_KEY'
+    #
+    #  doc = Vuzit::Document.find("DOCUMENT_ID")
+    #  puts doc.id
+    #  puts doc.title
+    def self.find(id)
+      timestamp = Time.now
+      sig = CGI.escape(Vuzit::Service::get_signature('show', id, timestamp))
+      # Create the connection
+      uri = URI.parse(Vuzit::Service.service_url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      query = "/documents/#{id}.xml?key=#{Vuzit::Service.public_key}" +
+              "&signature=#{sig}&timestamp=#{timestamp.to_i}"
+      request = Net::HTTP::Get.new(query)
+      response = http.start { http.request(request) }
+      # TODO: Check if response.code.to_i != 200
+      begin
+        doc = REXML::Document.new(response.body)
+      rescue Exception => ex
+        raise Vuzit::Exception.new("XML error: #{ex.message}")
+      end
+      if doc.root == nil
+        raise Vuzit::Exception.new("No response from server");
+      end
+      debug(response.code + " " + response.message + "\n" + response.body)
+      code = doc.root.elements['code']
+      if code != nil
+        raise Vuzit::Exception.new(doc.root.elements['msg'].text, code.text.to_i);
+      end
+      id = doc.root.elements['web_id']
+      if id == nil
+        raise Vuzit::Exception.new("Unknown error occurred");
+      end
+      result = Vuzit::Document.new
+      result.id = id.text
+      result.title = doc.root.elements['title'].text
+      result.subject = doc.root.elements['subject'].text
+      result.page_count = doc.root.elements['page_count'].text.to_i
+      result.page_width = doc.root.elements['width'].text.to_i
+      result.page_height = doc.root.elements['height'].text.to_i
+      result.file_size = doc.root.elements['file_size'].text.to_i
+      return result
+    end
+    # Uploads a file to Vuzit. It throws a Vuzit::Exception on failure.
+    #
+    # Example:
+    #
+    #  Vuzit::Service.public_key = 'YOUR_PUBLIC_API_KEY'
+    #  Vuzit::Service.private_key = 'YOUR_PRIVATE_API_KEY'
+    #
+    #  doc = Vuzit::Document.upload("c:/path/to/document.pdf", :secure => true)
+    #  puts doc.id
+    def self.upload(file, options = {})
+      raise ArgumentError, "Options must be a hash" unless options.kind_of? Hash
+      timestamp = Time.now
+      sig = Vuzit::Service::get_signature('create', nil, timestamp)
+      # Make a request form
+      fields = Hash.new
+      fields[:format] = 'xml'
+      fields[:key] = Vuzit::Service::public_key
+      if options[:secure] != nil
+        fields[:secure] = options[:secure] == true ? '1' : '0'
+      else
+        fields[:secure] = '1'
+      end
+      fields[:signature] = sig
+      fields[:timestamp] = timestamp.to_i
+      fields[:file_type] = options[:file_type]
+      response = nil
+      File.open(file, "rb") do |f|
+        fields[:upload] = f
+        response = send_request 'create', fields
+      end
+      debug(response.code + " " + response.message + "\n" + response.body)
+      # TODO: check the response.code.to_i to make sure it's 201
+      begin
+        doc = REXML::Document.new(response.body)
+      rescue Exception => ex
+        raise Vuzit::Exception.new("XML error: #{ex.message}")
+      end
+      if doc.root == nil
+        raise Vuzit::Exception.new("No response from server");
+      end
+      code = doc.root.elements['code']
+      if code != nil
+        raise Vuzit::Exception.new(doc.root.elements['msg'].text, code.text.to_i);
+      end
+      id = doc.root.elements['web_id']
+      if id == nil
+        raise Vuzit::Exception.new("Unknown error occurred");
+      end
+      result = Vuzit::Document.new
+      result.id = id.text
+      return result
+    end
+    private
+    # Sends debug messages if activated
+    def self.debug(text)
+      $stderr.puts(text) if Vuzit::Service::debug == true
+    end
+    # Makes a HTTP POST.
+    def self.send_request(method, fields = {})
+      # See if method is given
+      raise ArgumentError, "Method should be given" if method.nil? || method.empty?
+      debug("** Remote method call: #{method}; fields: #{fields.inspect}")
+      # replace pesky hashes to prevent accidents
+      fields = fields.stringify_keys
+      # Complete fields with the method name
+      fields['method'] = method
+      fields.reject! { |k, v| v.nil? }
+      debug("** POST parameters: #{fields.inspect}")
+      # Create the connection
+      uri = URI.parse(Vuzit::Service.service_url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      # API methods can be SLOW.  Make sure this is set to something big to prevent spurious timeouts
+      http.read_timeout = 15 * 60
+      request = Net::HTTP::Post.new('/documents')
+      request.multipart_params = fields
+      tries = TRIES
+      begin
+        tries -= 1
+        res = http.request(request)
+      rescue Exception
+        $stderr.puts "Request encountered error, will retry #{tries} more."
+        if tries > 0
+          # Retrying several times with sleeps is recommended.
+          # This will prevent temporary downtimes at Scribd from breaking API applications
+          sleep(20)
+          retry
+        end
+        raise $!
+      end
+      return res
+    end
+  end
+end

data/lib/vuzitruby/exception.rb ADDED Viewed

@@ -0,0 +1,33 @@
+module Vuzit
+  # Vuzit library exception handler class.
+  class Exception < StandardError
+    # The web service error message
+    attr_reader :message
+    # The web service error code
+    attr_reader :code
+    # Constructor for errors.
+    #
+    # Example:
+    #
+    #  begin
+    #    doc = Vuzit::Document.find("DOCUMENT_ID")
+    #  rescue Vuzit::Exception => ex
+    #    puts "Error code: #{ex.code}, message: #{ex.message}"
+    #  end
+    def initialize(message, code = 0)
+      @message = message
+      @code = code
+    end
+    # Returns the string representation of the error in this format:
+    #
+    #  Vuzit::Exception: [CODE]: MESSAGE
+    def to_s
+      return "Vuzit::Exception: [#{@code}]: #{@message}";
+    end
+  end
+end

data/lib/vuzitruby/service.rb ADDED Viewed

@@ -0,0 +1,149 @@
+require 'net/https'
+require "rubygems"
+require "mime/types" # Requires gem install mime-types
+require "base64"
+require 'cgi'
+require 'md5'
+module Net #:nodoc:all
+  # Enhances the HTTP::Post class for multi-part post transactions
+  class HTTP::Post
+    def multipart_params=(param_hash={})
+      boundary_token = [Array.new(8) {rand(256)}].join
+      self.content_type = "multipart/form-data; boundary=#{boundary_token}"
+      boundary_marker = "--#{boundary_token}\r\n"
+      self.body = param_hash.map { |param_name, param_value|
+        boundary_marker + case param_value
+        when File
+          file_to_multipart(param_name, param_value)
+        else
+          text_to_multipart(param_name, param_value.to_s)
+        end
+      }.join('') + "--#{boundary_token}--\r\n"
+    end
+    protected
+    def file_to_multipart(key,file)
+      filename = File.basename(file.path)
+      mime_types = MIME::Types.of(filename)
+      mime_type = mime_types.empty? ? "application/octet-stream" : mime_types.first.content_type
+      part = %Q|Content-Disposition: form-data; name="#{key}"; filename="#{filename}"\r\n|
+      part += "Content-Transfer-Encoding: binary\r\n"
+      part += "Content-Type: #{mime_type}\r\n\r\n#{file.read}\r\n"
+    end
+    def text_to_multipart(key,value)
+      "Content-Disposition: form-data; name=\"#{key}\"\r\n\r\n#{value}\r\n"
+    end
+  end
+end
+module Vuzit
+  # Global data class.
+  class Service
+    @@public_key = nil
+    @@private_key = nil
+    @@service_url = 'http://vuzit.com'
+    @@debug = false
+    # TODO: For all of the set variables do not allow nil values
+    # Sets the Vuzit public API key
+    def self.public_key=(value)
+      @@public_key = value
+    end
+    # Returns the Vuzit public API key
+    def self.public_key
+      @@public_key
+    end
+    # Sets Vuzit private API key. Do NOT share this with anyone!
+    def self.private_key=(value)
+      @@private_key = value
+    end
+    # Returns the Vuzit private API key. Do NOT share this with anyone!
+    def self.private_key
+      @@private_key
+    end
+    # Sets the URL of the Vuzit web service.  This only needs to be changed if
+    # you are running Vuzit Enterprise on your own server.
+    # The default value is "http://vuzit.com"
+    def self.service_url=(value)
+      @@service_url = value
+    end
+    # Returns the URL of the Vuzit web service.
+    def self.service_url
+      @@service_url
+    end
+    # Switch this to _true_ if you would like to see debug messages in the
+    # output.
+    def self.debug=(value)
+      @@debug = value
+    end
+    # Returns whether debugging is turned on or off.
+    def self.debug
+      @@debug
+    end
+    # Returns The signature string.  NOTE: If you are going to use this
+    # with the Vuzit Javascript API then the value must be encoded with the
+    # CGI.escape function.  See the Wiki example for more information:
+    #
+    #   http://wiki.github.com/vuzit/vuzitruby/code-samples
+    #
+    # Example:
+    #
+    #  timestamp = Time.now
+    #  sig = Vuzit::Service.get_signature("show", "DOCUMENT_ID", timestamp)
+    def self.get_signature(service, id = '', time = nil)
+      if Vuzit::Service.public_key == nil || Vuzit::Service.private_key == nil
+        raise Vuzit::Exception.new("The public_key or private_key variables are nil")
+      end
+      time = (time == nil) ? Time.now.to_i : time.to_i
+      if @@public_key == nil
+        raise Vuzit::Exception.new("Vuzit::Service.public_key not set")
+      end
+      if @@private_key == nil
+        raise Vuzit::Exception.new("Vuzit::Service.private_key not set")
+      end
+      msg = "#{service}#{id}#{@@public_key}#{time}"
+      hmac = hmac_sha1(@@private_key, msg)
+      result = Base64::encode64(hmac).chomp
+      return result
+    end
+    private
+    # Creates the SHA1 key.
+    def self.hmac_sha1(key, s)
+      ipad = [].fill(0x36, 0, 64)
+      opad = [].fill(0x5C, 0, 64)
+      key = key.unpack("C*")
+      key += [].fill(0, 0, 64-key.length) if key.length < 64
+      inner = []
+      64.times { |i| inner.push(key[i] ^ ipad[i]) }
+      inner += s.unpack("C*")
+      outer = []
+      64.times { |i| outer.push(key[i] ^ opad[i]) }
+      outer = outer.pack("c*")
+      outer += Digest::SHA1.digest(inner.pack("c*"))
+      return Digest::SHA1.digest(outer)
+    end
+  end
+end

data/lib/vuzitruby.rb ADDED Viewed

@@ -0,0 +1,9 @@
+$:.unshift(File.dirname(__FILE__))
+# This prevents the "require 'some_gem'" error
+require 'rubygems'
+require 'vuzitruby/service'
+require 'vuzitruby/document'
+require 'vuzitruby/exception'

metadata ADDED Viewed

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: vuzitruby
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Brent Matzelle
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2009-03-30 00:00:00 -04:00
+default_executable:
+dependencies: []
+description: This is a library for the Vuzit Web Services API.  For  more information on the platform, visit  http://vuzit.com/developer
+email: support@vuzit.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README
+files:
+- README
+- Rakefile
+- lib/vuzitruby.rb
+- lib/vuzitruby/document.rb
+- lib/vuzitruby/exception.rb
+- lib/vuzitruby/service.rb
+has_rdoc: true
+homepage: http://vuzit.com/
+post_install_message:
+rdoc_options:
+- --main
+- README
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: "0"
+  version:
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: "0"
+  version:
+requirements: []
+rubyforge_project: vuzitruby
+rubygems_version: 1.3.1
+signing_key:
+specification_version: 2
+summary: Ruby client library for the Vuzit Web Services API
+test_files: []