interfax 0.1.3 → 0.2.0

data/README.markdown

@@ -1,7 +1,12 @@
 # Interfax/Ruby
 
-This library is a wrapper for the interfax.net fax service. Until now only sending of html faxes and status 
-querying is supported.
+This library is a wrapper for the interfax.net fax service. For now,
+you can do the following:
+
+* Send HTML faxes
+* Query the status of a sent fax
+* Retrieve a list of incoming faxes
+* Get the image for a sent fax
 
 If you're willing to help, just drop me a line.
 
@@ -11,6 +16,8 @@ If you're willing to help, just drop me a line.
 
 ## Usage
 
+### Outgoing Faxes
+
 Create a class, inherit from Interfax::Base and set authentication parameters:
 
     class OrderFax < Interfax::Base
@@ -19,7 +26,7 @@ Create a class, inherit from Interfax::Base and set authentication parameters:
     end
 
 
-### Sending
+#### Sending Faxes
 
 Creating a fax:
 
@@ -37,7 +44,7 @@ Finally:
 
     result_id = fax.deliver
 
-### Querying
+#### Getting Sent Faxes
 
 To get all faxes:
 
@@ -55,6 +62,59 @@ or get more than one at once:
 
     OrderFax.find(123456789,234567890)
 
+
+### Incoming Faxes
+
+
+#### Getting Incoming Faxes
+
+To get a list of incoming faxes, you can either use the base class:
+
+    Interfax::Incoming.username      = 'my_interfax_username'
+    Interfax::Incoming.password      = 'my_interfax_password'
+    Interfax::Incoming.limit         = 15    # optional, default 100
+    Interfax::Incoming.mark_as_read  = false # optional, default false
+    
+    # fetch unread incoming faxes
+    faxes = Interfax::Incoming.new
+
+If you want you can define your own subclass -- useful for keeping
+authentication info handy -- you can do so:
+
+    class IncomingFaxes < Interfax::Incoming
+      self.username = 'my_interfax_username'
+      self.password = 'my_interfax_password'
+    end
+
+    # fetch all incoming faxes
+    faxes = Interfax::Incoming.all
+
+There are four methods for fetching incoming faxes:
+
+    #all               - Fetch all incoming faxes 
+    #unread            - Fetch unread incoming faxes
+    #account_all       - Fetch incoming faxes for all users on your account
+    #account_unread    - Fetch unread incoming faxes for all users on your account
+
+The account_ methods require that you have admin privileges. For more
+information, see the Interfax API documentation.
+
+
+#### Getting Incoming Fax Images
+
+The Interfax::Incoming methods described above return an array of
+instances of the class you called it on. If you're using the
+Interfax::Incoming class you'll get those. If you use a subclass,
+we'll instantiate that class and return an array of those.
+
+In either event, call the `#image` method to fetch the PDF/TIF of the
+fax as a string, suitable for writing to the filesystem in the normal fashion.
+
+    # Assume you've defined a sublcass as above
+    all_faxes = IncomingFaxes.all
+    all_faxes[0].image # return the first fax's image
+
+
 ## Interfax API documentation
 
 http://www.interfax.net/en/dev/webservice/reference/methods

data/VERSION

@@ -1 +1 @@
-0.1.3
+0.2.0

data/lib/interfax/incoming.rb

@@ -0,0 +1,204 @@
+require 'soap/wsdlDriver'
+require 'Base64'
+
+module Interfax
+
+  # = Interfax::Incoming
+  #
+  # Allows interaction with the Interfax Inbound API, documented at:
+  # http://www.interfax.net/en/dev/webservice/reference_in
+  #
+  # == Retrieving incoming faxes
+  #
+  # Set the +username+ and +password+ variables appropriately, and
+  # then call one of the query methods, which are described in further
+  # detail below.
+  # 
+  #   Interfax::Incoming.username = 'my_interfax_username'
+  #   Interfax::Incoming.password = 'my_interfax_password'
+  #   faxes = Interfax::Incoming.unread
+  #
+  # You can extend Interfax::Incoming, and the query methdos will
+  # return instances of your subclass. This is useful for extending
+  # functionality, or consolidating your configuration in one place.
+  #
+  #   class InboundFax < Interfax::Incoming
+  #     self.username = 'my_interfax_username'
+  #     self.password = 'my_interfax_password'
+  #
+  #     def write_image_to_file
+  #       File.open("/path/to/file", 'w') { |f| f.write(image)
+  #     end
+  #   end
+  #
+  #   faxes = InboundFax.all # this is an array of InboundFax objects
+  #   faxes.map(&:write_image_to_file)
+  #
+  # == Methods
+  #
+  # The methods available for fetching or querying inbound faxes are:
+  #
+  # * +#all+ - Retrieves all inbound faxes, up to +limit+.
+  # * +#unread+ - Retrieves any unread faxes, up to +limit+.
+  # * +#account_all+ - Retrieves inbound faxes for all users on your
+  #   account, up to +limit+. Requires an administrator account.
+  # * +#account_unread+ - Same as above, but fetches only unread
+  #   faxes. Also requires an administrator account.
+  #
+  # As seen above, these methods return instances of the class they're
+  # called on, which makes it easy to extend your objects for custom
+  # functionality. 
+  #
+  # == Configuration
+  #
+  # We require that the following two configuration variables be set
+  # at the class level, as seen in the examples above.
+  #
+  # * +username+ - [required] Your interfax username.
+  # * +password+ - [requierd] Your interfax password.
+  #
+  # We also support a few other configuration methods, which are
+  # explained further in Interfax's API documentation.
+  #
+  # * +limit+ - [1..100, default 100] The maximum number of faxes to return.
+  # * +mark_as_read+ - [boolean, default false] Whether or not to mark
+  #   retrieved faxes as sent.
+  #
+  # These options are also accepted as options when requesting faxes:
+  #
+  #   # Assume username/password already set
+  #   Interfax::Incoming.all(:limit => 10, :mark_as_read => true)
+  #
+  # Options supplied this way will temporarily override any options
+  # set on the class.
+  
+  class Incoming
+    
+    class << self
+      attr_accessor :username, :password, :mark_as_read, :limit #:nodoc:
+
+      def soap_client #:nodoc:
+        SOAP::WSDLDriverFactory.
+          new("https://ws.interfax.net/inbound.asmx?WSDL").
+          create_rpc_driver
+      end
+      
+      def query(type, opts = {}) #:nodoc:
+        result = self.soap_client.GetList(:Username => self.username,
+                  :Password => self.password,
+                  :MaxItems => opts[:limit] || self.limit || 100,
+                  :MarkAsRead => opts[:mark_as_read] || self.mark_as_read || false,
+                  :LType => type
+                  )
+        
+        return [] if result.nil? || !defined?(result.objMessageItem)
+        [*result.objMessageItem.messageItem].map do |fax|
+          self.new(fax.messageID, fax.messageSize)
+        end
+      end
+
+      # Returns all inbound messages for your user up to the +limit+
+      # option. Optionally marks the faxes as read.
+      #
+      # ==== Options (as hash)
+      #
+      # Both of these will default to whatever values you've set for
+      # the class, or 100 (limit) or false (mark_as_read) if you haven't.
+      # * +:limit+ - Maximum number of faxes to return.
+      # * +:mark_as_read+: Mark fetched faxes as read.
+     
+      def all(opts = {})
+        query('AllMessages', opts)
+      end
+      
+      # Returns any unread messages for your user up to the +limit+
+      # option. Optionally marks the faxes as read.
+      #
+      # ==== Options (as hash)
+      #
+      # Both of these will default to whatever values you've set for
+      # the class, or 100 (limit) or false (mark_as_read) if you haven't.
+      # * +:limit+ - Maximum number of faxes to return.
+      # * +:mark_as_read+: Mark fetched faxes as read.
+      
+      def unread(opts = {})
+        query('NewMessages', opts)
+      end
+      
+      # Returns all messages for all users on your account, up
+      # to the +limit+ option. Optionally marks the faxes as
+      # read. Requires your user be an administrator for your account.
+      #
+      # ==== Options (as hash)
+      #
+      # Both of these will default to whatever values you've set for
+      # the class, or 100 (limit) or false (mark_as_read) if you haven't.
+      # * +:limit+ - Maximum number of faxes to return.
+      # * +:mark_as_read+: Mark fetched faxes as read.
+      
+      def account_all(opts = {})
+        query('AccountAllMessages', opts)
+      end
+
+      # Returns any unread messages for all users on your account, up
+      # to the +limit+ option. Optionally marks the faxes as
+      # read. Requires your user be an administrator for your account.
+      #
+      # ==== Options (as hash)
+      #
+      # Both of these will default to whatever values you've set for
+      # the class, or 100 (limit) or false (mark_as_read) if you haven't.
+      # * +:limit+ - Maximum number of faxes to return.
+      # * +:mark_as_read+: Mark fetched faxes as read.
+
+      def account_unread(opts = {})
+        query('AccountNewMessages', opts)
+      end
+      
+    end
+
+
+
+    attr_accessor :username, :password, :mark_as_read, :chunk_size, :message_id, :message_size, :image #:nodoc:
+    
+    def initialize(message_id, message_size)
+      @username = self.class.username
+      @password = self.class.password
+      @mark_as_read = self.class.mark_as_read || false
+      @chunk_size = 100000
+      @message_id = message_id
+      @message_size = message_size.to_i
+      @image = nil
+    end
+
+    # Retrieves the image from the Interfax Inbound API, as a
+    # string. Suitable for writing to a file or streaming to a client.
+    def image
+      @image || fetch_image
+    end
+    
+    def fetch_image #:nodoc:
+      @image = ""
+      downloaded_size = 0
+      while downloaded_size < @message_size
+        result = self.class.soap_client.GetImageChunk(:Username => @username,
+                                                :Password => @password,
+                                                :MessageID => @message_id,
+                                                :MarkAsRead => @mark_as_read,
+                                                :ChunkSize => @chunk_size,
+                                                :From => downloaded_size)
+
+        # TODO: Make this throw a nicer exception on failure
+        if defined?(result.image)
+          @image << Base64.decode64(result.image)
+        end
+        downloaded_size += @chunk_size
+
+      end
+      
+      @image
+    end
+
+  end
+
+end

data/lib/interfax.rb

@@ -5,4 +5,5 @@ $:.unshift(File.dirname(__FILE__)) unless
   $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
 
 require 'interfax/fax_item'
-require 'interfax/base'
+require 'interfax/base'
+require 'interfax/incoming'

data/spec/incoming_helper.rb

@@ -0,0 +1,11 @@
+module IncomingHelper
+  
+  class MockInterfaxResponse < Struct.new(:objMessageItem); end
+  class ObjMessageItem < Struct.new(:messageItem); end
+  class MessageItem < Struct.new(:messageID, :messageSize); end
+  
+
+  def mock_getlist_response(count = 1)
+    MockInterfaxResponse.new(ObjMessageItem.new([MessageItem.new('messageid', '200000')] * count))
+  end
+end

data/spec/incoming_spec.rb

@@ -0,0 +1,107 @@
+require 'spec_helper'
+include IncomingHelper
+
+describe Interfax::Incoming do
+  
+  before(:each) do
+    @client_mock = mock("SoapClient",
+                        :GetList => true,
+                        :GetImageChunk => true)
+    
+    Interfax::Incoming.stub!(:soap_client).and_return(@client_mock)
+  end
+
+  context "querying for incoming faxes" do
+
+    it "should query for all messages" do
+      Interfax::Incoming.should_receive(:query).with('AllMessages', anything())
+      Interfax::Incoming.all
+    end
+
+    it "should query for unread messages" do
+      Interfax::Incoming.should_receive(:query).with('NewMessages', anything())
+      Interfax::Incoming.unread
+    end
+
+    it "should query for all users' unread messages" do
+      Interfax::Incoming.should_receive(:query).with('AccountNewMessages', anything())
+      Interfax::Incoming.account_unread
+    end
+
+    it "should query for all users' messages" do
+      Interfax::Incoming.should_receive(:query).with('AccountAllMessages', anything())
+      Interfax::Incoming.account_all
+    end
+
+    it "should respect the :limit argument over a class-defined limit" do
+      @client_mock.should_receive(:GetList).with(hash_including(:MaxItems => 24))
+      Interfax::Incoming.limit = 50
+      Interfax::Incoming.all(:limit => 24)
+    end
+
+    it "should use the class-specified limit over the default" do
+      @client_mock.should_receive(:GetList).with(hash_including(:MaxItems => 50))
+      Interfax::Incoming.limit = 50
+      Interfax::Incoming.all
+    end
+
+    it "should respect the :mark_as_read argument over the class-defined value" do
+      @client_mock.should_receive(:GetList).with(hash_including(:MarkAsRead => true))
+      Interfax::Incoming.mark_as_read = false
+      Interfax::Incoming.all(:mark_as_read => true)
+    end
+
+    it "should use the class-specified mark_as_read over the default" do
+      @client_mock.should_receive(:GetList).with(hash_including(:MarkAsRead => true))
+      Interfax::Incoming.mark_as_read = true
+      Interfax::Incoming.all
+    end
+
+
+    it "should return instances of the base class when called on the base class" do
+      @client_mock.stub!(:GetList).and_return(mock_getlist_response)
+      Interfax::Incoming.all[0].class.should == Interfax::Incoming
+    end
+
+    it "should return instances of the subclass when called on a subclass" do
+      class TestFax < Interfax::Incoming; end
+
+      @client_mock.
+        stub!(:GetList).
+        and_return(mock_getlist_response)
+      TestFax.stub!(:soap_client).and_return(@client_mock)
+
+      TestFax.all[0].class.should == TestFax
+    end
+    
+  end
+
+  context "fetching images" do
+
+    before(:each) do 
+      @fax = Interfax::Incoming.new('message_id', '200000')
+    end
+
+    it "should fetch the image when asked" do
+      @client_mock.should_receive(:GetImageChunk).at_least(:once)
+      @fax.image
+    end
+
+    it "should cache the image once received" do
+      @client_mock.should_receive(:GetImageChunk).at_least(:once)
+      @fax.image
+      @client_mock.should_not_receive(:GetImageChunk)
+      @fax.image
+    end
+
+    it "should respect the class-defined mark_as_read option" do
+      Interfax::Incoming.mark_as_read = true
+      @client_mock.should_receive(:GetImageChunk).with(hash_including(:MarkAsRead => true))
+      @fax.image
+    end
+
+    
+  end
+  
+end
+

data/spec/interfax_spec.rb

@@ -2,6 +2,6 @@ require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
 describe "Interfax" do
   it "fails" do
-    fail "hey buddy, you should probably rename this file and start specing for real"
+    pending "hey buddy, you should probably rename this file and start specing for real"
   end
 end

data/spec/spec_helper.rb

@@ -3,6 +3,7 @@ $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 require 'interfax'
 require 'spec'
 require 'spec/autorun'
+require 'incoming_helper'
 
 Spec::Runner.configure do |config|
   

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: interfax
 version: !ruby/object:Gem::Version 
-  hash: 29
   prerelease: false
   segments: 
   - 0
-  - 1
-  - 3
-  version: 0.1.3
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Sascha Brink
@@ -15,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-20 00:00:00 +01:00
+date: 2011-04-28 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -26,7 +25,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 13
         segments: 
         - 1
         - 2
@@ -51,6 +49,9 @@ files:
 - lib/interfax.rb
 - lib/interfax/base.rb
 - lib/interfax/fax_item.rb
+- lib/interfax/incoming.rb
+- spec/incoming_helper.rb
+- spec/incoming_spec.rb
 - spec/interfax_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
@@ -68,7 +69,6 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
@@ -77,7 +77,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
@@ -89,5 +88,7 @@ signing_key:
 specification_version: 3
 summary: A ruby wrapper for the interfax webservice (SOAP)
 test_files: 
+- spec/incoming_helper.rb
+- spec/incoming_spec.rb
 - spec/interfax_spec.rb
 - spec/spec_helper.rb