interfax 0.2.1 → 1.0.0.beta.1

data/README.markdown

@@ -1,134 +0,0 @@
-# Interfax/Ruby
-
-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.
-
-## Installation
-
-    gem install interfax
-
-## Usage
-
-### Outgoing Faxes
-
-Create a class, inherit from Interfax::Base and set authentication parameters:
-
-    class OrderFax < Interfax::Base
-      self.username = "my_interfax_username"
-      self.password = "my_interfax_password"
-    end
-
-
-#### Sending Faxes
-
-Creating a fax:
-
-    fax = OrderFax.new(:html).contains("<h1>test</h1>").subject("test").to("+4923456123456")
-
-It is possible to specify more than one receipent:
-
-    fax = OrderFax.new(:html).contains("<h1>test</h1>").subject("test").to(["+4923456123456","+4943254324312"])
-
-To get a summary before sending, just call summary on it which returns a hash:
-
-    fax.summary
-
-Finally:
-
-    result_id = fax.deliver
-
-#### Getting Sent Faxes
-
-To get all faxes:
-
-    faxes = OrderFax.all
-  
-You can limit the number of received items with an optional parameter:
-    
-    faxes = OrderFax.all(10)
-
-To find a specific fax:
-
-    OrderFax.find(123456789)
-
-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
-
-## Note on Patches/Pull Requests
- 
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
-
-## Copyright
-
-Copyright (c) 2010 Sascha Brink. See LICENSE for details.

data/Rakefile

@@ -1,46 +0,0 @@
-require 'rubygems'
-require 'rake'
-
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "interfax"
-    gem.summary = %Q{A ruby wrapper for the interfax webservice (SOAP)}
-    gem.description = %Q{A ruby wrapper for the interfax webservice (SOAP)}
-    gem.email = "sascha.brink@gmail.com"
-    gem.homepage = "http://github.com/sbrink/interfax"
-    gem.authors = ["Sascha Brink"]
-    gem.add_development_dependency "rspec", ">= 1.2.9"
-    gem.files =  FileList["[A-Z]*", "{lib,spec}/**/*"] - FileList["**/*.log"]
-    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
-  end
-  Jeweler::GemcutterTasks.new
-rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
-end
-
-#require 'spec/rake/spectask'
-#Spec::Rake::SpecTask.new(:spec) do |spec|
-#  spec.libs << 'lib' << 'spec'
-#  spec.spec_files = FileList['spec/**/*_spec.rb']
-#end
-
-#Spec::Rake::SpecTask.new(:rcov) do |spec|
-#  spec.libs << 'lib' << 'spec'
-#  spec.pattern = 'spec/**/*_spec.rb'
-#  spec.rcov = true
-#end
-
-task :spec => :check_dependencies
-
-task :default => :spec
-
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "interfax #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end

data/VERSION

@@ -1 +0,0 @@
-0.2.1

data/lib/interfax/base.rb

@@ -1,120 +0,0 @@
-
-module Interfax
-
-  class Base
-    
-    # Class methods
-    
-    class << self
-      attr_accessor :username, :password
-
-      def query(verb,verbdata,limit=-1)
-        result = SOAP::WSDLDriverFactory.new("https://ws.interfax.net/dfs.asmx?WSDL").create_rpc_driver.FaxQuery(
-          :Username => self.username,
-          :Password => self.password,
-          :Verb => verb,
-          :VerbData => verbdata,
-          :MaxItems => limit,
-          :ResultCode => 0
-        )
-        return [] if result.nil? || !defined?(result.faxQueryResult)
-        [*result.faxQueryResult.faxItemEx].map do |f| 
-          FaxItem.new(
-            f.transactionID,
-            Time.parse(f.submitTime),
-            Time.parse(f.postponeTime),
-            f.destinationFax,
-            f.duration,
-            f.remoteCSID,
-            f.pagesSent,
-            f.status,
-            f.subject,
-            f.pagesSubmitted)
-        end  
-      end
-      
-      def find(*args)
-        query("IN", args.join(','))
-      end
-
-      def last(limit=1)
-        query("LE","999999999",limit)
-      end
-      
-      def all()
-        query("LE","999999999")
-      end
-
-    end
-
-    # Instance methods
-
-    def initialize(type="HTML",content=nil)
-      @username = self.class.username
-      @password = self.class.password
-      @type = type.to_s.upcase
-      @content = content
-      @at = Time.now
-      @recipients = nil
-      @subject = "Change me"
-      @retries = "0"
-    end
-    
-    def contains(content)
-      @content = content
-      self
-    end
-    
-    def to(recipients)
-      @recipients = [*recipients].join(";")
-      self
-    end
-    
-    def subject(subject)
-      @subject = subject
-      self
-    end
-    
-    def retries(count)
-      @retries = count.to_s
-      self
-    end
-    
-    def at(time)
-      @at = time
-      self
-    end
-    
-    def summary
-      { 
-        :fax_numbers => @recipients, 
-        :content => @content,
-        :at => @at,
-        :retries => @retries,
-        :subject => @subject,
-        :username => @username
-      }
-    end
-    
-    def deliver
-      result = SOAP::WSDLDriverFactory.new("https://ws.interfax.net/dfs.asmx?WSDL").create_rpc_driver.SendfaxEx_2(
-        :Username => @username,
-        :Password => @password,
-        :FileTypes => @type,
-        :Postpone => @at,
-        :RetriesToPerform => @retries,
-        :FaxNumbers=> @recipients,
-        :FilesData => @content,
-        :FileSizes => @content.size,
-        :Subject => @subject,
-        :PageSize => 'A4',
-        :PageOrientation => 'Portrait',
-        :IsHighResolution => 'true',
-        :IsFineRendering => 'false'
-      )
-      result ? result.sendfaxEx_2Result : nil
-    end
-    
-  end
-
-end

data/lib/interfax/fax_item.rb

@@ -1,13 +0,0 @@
-module Interfax
-
-  class FaxItem < Struct.new(:id, :submit_time, :postpone_time, :receiver_number, :duration, :remote_csid, :sent_pages, :status, :subject, :submitted_pages)
-    def pages
-      "#{sent_pages}/#{submitted_pages}"
-    end
-    
-    def ok
-      (status.to_i >= 0) ? true : false
-    end
-  end
-
-end

data/lib/interfax/incoming.rb

@@ -1,223 +0,0 @@
-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)
-        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
-
-    # class methods
-
-    attr_accessor :username, :password, :mark_as_read, :chunk_size, :message_id, :message_size, :image,
-      :interfax_number, :remote_csid, :message_status, :pages, :message_type, :receive_time, :caller_id, 
-      :duration
-    
-    # Normally this is instantied for you as a result of calling one of the
-    # querying class methods. If you want to instantiate an object yourself,
-    # you can pass it the results of the GetList API call, or any object that
-    # looks like it.
-    # See: http://www.interfax.net/en/dev/webservice/reference/getlist
-    def initialize(params = nil)
-      @username = self.class.username
-      @password = self.class.password
-      @mark_as_read = self.class.mark_as_read || false
-      @chunk_size = 100000
-
-      unless params.nil?
-        @message_id = params.messageID
-        @message_size = params.messageSize.to_i
-        @interfax_number = params.phoneNumber
-        @remote_csid = params.remoteCSID
-        @message_status = params.messageStatus
-        @pages = params.pages
-        @message_type = params.messageType
-        @receive_time = params.receiveTime
-        @caller_id = params.callerID
-        @duration = params.messageRecordingDuration
-      end
-      
-      @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