sr_fax 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 56a3f8e6fc0de9b9777780d6a53e07b0321d8dcc
-  data.tar.gz: a0a385e62d210e72b916e66bc2607855074333d1
+  metadata.gz: b08b8fbb2726537e1c481371db271bd81a630689
+  data.tar.gz: 12939f123b696d6bc753e275cd18cf7821184f78
 SHA512:
-  metadata.gz: 255ad2006904e751d180537d21de052a0038ee23d47405bd446f7e8d9eac9e83e395f3dc20b464972c2a2f6a290eb5ce1815c377861594b9b2a52dd020e8a0ce
-  data.tar.gz: 6baffe09500daa159d920a1c6bcd088faf3c3c08310441b0c9f089aa2687379777c45629a9316119b1e45c21004caa751d0589f77f2d9397749eed1fc6b403f7
+  metadata.gz: b3ba7b257586a528df2983a692ba24fc77cbc115125882fa478c55917ac979674a25c3a220426dceccdabbb638d06f78a9debda3b4fab077d76274f6be5197ec
+  data.tar.gz: 03a576e0bc5b91855ff6737ae4dc1ac547673863d167d79e29f564a2f15639d4c5fc7cddbd17c7f08301cd8e53ae932a0bf0150d6f1be71d5e75e3b80bfb2f2f

data/Gemfile

@@ -1,8 +1,4 @@
 source 'https://rubygems.org'
 
-group :development do
-  gem "yard", "~> 0.8"
-end
-
 # Specify your gem's dependencies in srfax.gemspec
 gemspec

data/README.md

@@ -22,9 +22,9 @@ Or install it yourself using:
 
 To get started, simply open the console view and require the SrFax module.  Once you have completed that, enter your account credentials using the SrFax setup block, and then begin to execute calls. All status' returned are simply formatted hashes from the SrFax service.
 
-```sh
+```ruby
 
-require 'SrFax'
+require 'srfax'
 
 SrFax.setup do |config|
   config.defaults[:access_id] = '1234'
@@ -37,6 +37,12 @@ SrFax.update_fax_status(descriptor, direction)
 SrFax.get_fax(descriptor, direction, {:sMarkasViewed => 'Y'} 
 ```
 
+As an example, here is a sample queue fax call to send a fax
+
+```ruby
+SrFax.queue_fax "yourname@yourdomain.com", "SINGLE", "18888888888", {sFileName_1: "file1.txt", sFileContent_1: Base64.encode64("Sample Fax")}
+```
+
 The SrFax module currently supports the following functions
   - Sending and receiving faxes
   - Updating flags on the inbox or outbox faxes

data/bin/console

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 require "bundler/setup"
-require "SrFax"
+require "srfax"
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.

data/lib/srfax.rb

@@ -1,5 +1,7 @@
-require 'RestClient'
+require 'restclient'
 require 'active_support'
+require 'active_support/core_ext/hash'
+require 'version'
 
 # This class serves as the integration component between the application and the SRFax cloud service.
 # API DOX available @ https://www.srfax.com/srf/media/SRFax-REST-API-Documentation.pdf.  
@@ -12,18 +14,15 @@ require 'active_support'
 #  Get_Fax_Outbox - Returns a list of faxes sent for a specified period of time
 #  Retrieve_Fax – Returns a specified sent or received fax file in PDF or TIFF format
 #  Delete_Fax - Deletes specified received or sent faxes
-#
-#  Unimplemented:
 #  Get_FaxStatus – Determines the status of a fax that has been scheduled for delivery.
 #  Get_MultiFaxStatus – Determines the status of a multiple faxes that hav been
 #     scheduled for delivery.
-#  Delete_Pending_Fax - Deletes a specified queued fax which has not been processed
 #  Stop_Fax - Removes a scheduled fax from the queue
+# Unimplemented methods:
+#  Delete_Pending_Fax - THIS DOESN'T EXIST - but is documented to exist
 module SrFax
-  VERSION = '0.3.0pre'
-
   # Base URL for accessing SRFax API
-  BASE_URI = "https://www.srfax.com/SRF_SecWebSvc.php"
+  BASE_URL = "https://www.srfax.com/SRF_SecWebSvc.php"
 
   mattr_accessor :defaults
   # Default values hash to use with all #execute commands
@@ -31,12 +30,14 @@ module SrFax
     access_id: '1234',
     access_pwd: 'password',
     sFaxFormat: 'PDF', # Default format, PDF or TIF
+    sCallerID: '5555555555', # MUST be 10 digits
     sResponseFormat: 'JSON' # XML or JSON
   }
 
   mattr_accessor :logger
   # Logger object for use in standalone modeo or with Rails
   @@logger = defined?(Rails) ? Rails.logger : Logger.new(STDOUT)
+  @@logger.level = Logger::INFO
 
   class << self
     # Allow configuring Srfax with a block, these will be the methods default values for passing to 
@@ -48,6 +49,7 @@ module SrFax
     #   Srfax.setup do |config|
     #     config.defaults[:access_id] = '1234'
     #     config.defaults[:access_pwd] = 'password'
+    #     config.defaults[:sCallerID] = '5555555555'
     #   end
     def setup(&block)
       yield self
@@ -66,10 +68,10 @@ module SrFax
     #
     # Example Payload for Return: 
     #   {"Status"=>"Success", "Result"=>[{"FileName"=>"20150430124505-6104-19_1|20360095", "ReceiveStatus"=>"Ok", 
-    #   "Date"=>"Apr 30/15 02:45 PM", "EpochTime"=>1430423105, "CallerID"=>"9056193547", "RemoteID"=>"", "Pages"=>"1", 
+    #   "Date"=>"Apr 30/15 02:45 PM", "EpochTime"=>1430423105, "CallerID"=>"5555555555", "RemoteID"=>"", "Pages"=>"1", 
     #   "Size"=>"5000", "ViewedStatus"=>"N"} ]}
     def view_inbox(status = 'UNREAD', options = {})
-      logger.info("Checking fax inbox from cloud service")
+      logger.debug "Checking fax inbox from cloud service"
       postVariables = { 
         :action => "Get_Fax_Inbox", 
         :sViewedStatus => status.upcase
@@ -95,13 +97,9 @@ module SrFax
     #
     # Example Payload for Return: 
     #   {"Status"=>"Success", "Result"=>[{"UserID"=>1234, "Period"=>"ALL", 
-    #   "ClientName"=>nil, "SubUserID"=>0, "BillingNumber"=>"8669906402", "NumberOfFaxes"=>5, "NumberOfPages"=>8}]}
-    #
-    # optional variables 
-    #   sPeriod: (ALL or RANGE), sStartDate: YYYYMMDD, sEndDate: YYYYMMDD
-    #   sIncludeSubUsers: Y or N  (if you want to see all faxes on subaccounts as well)
+    #   "ClientName"=>nil, "SubUserID"=>0, "BillingNumber"=>"8888888888", "NumberOfFaxes"=>5, "NumberOfPages"=>8}]}
     def view_usage(options = {})
-      logger.info "Viewing fax usage from cloud service"
+      logger.debug "Viewing fax usage from cloud service"
       postVariables = { :action => "Get_Fax_Usage" }
       res = execute(postVariables)
       return res
@@ -116,7 +114,7 @@ module SrFax
     # @option options [String] :sIncludeSubUsers Include subuser accounts ('Y' or 'N')
     # @return [Hash] A hash containing the return value (Success/Failure) and the payload where applicable
     def view_outbox(options = {})
-      logger.info "Viewing fax outbox from cloud service"
+      logger.debug "Viewing fax outbox from cloud service"
       postVariables = { :action => "Get_Fax_Outbox" }
       res = execute(postVariables)
   
@@ -138,14 +136,14 @@ module SrFax
     # @option options [String] :sFaxFormat Update the format to retrieve the file in ('PDF' or 'TIFF')
     # @return [Hash] A hash containing the return value (Success/Failure) and the payload where applicable
     def get_fax(descriptor, direction, options = {}) 
-      logger.info "Retrieving fax from cloud service in the direction of '#{direction}', Descriptor:'#{descriptor}'"
+      logger.debug "Retrieving fax from cloud service in the direction of '#{direction}', Descriptor:'#{descriptor}'"
       faxname,faxid = descriptor.split('|')
       if (faxname.nil? or faxid.nil?)
-        logger.info "Valid descriptor not provided to get_fax function call.  Descriptor:'#{descriptor}'"
+        logger.debug "Valid descriptor not provided to get_fax function call.  Descriptor:'#{descriptor}'"
         return nil
       end
   
-      logger.info "Retrieving fax from cloud service"
+      logger.debug "Retrieving fax from cloud service"
       postVariables = {   
         :action => "Retrieve_Fax",
         :sFaxFileName => descriptor,
@@ -165,10 +163,10 @@ module SrFax
     # @option options [String] :sMarkasViewed Update the fax status to viewed (or unviewed). Accepts 'Y' or 'N'.  Defaults to Y
     # @return [Hash] A hash containing the return value (Success/Failure) and the payload where applicable
     def update_fax_status(descriptor, direction, options = {})
-      logger.info "Updating a fax in the cloud service in the direction of '#{direction}', Descriptor:'#{descriptor}'"
+      logger.debug "Updating a fax in the cloud service in the direction of '#{direction}', Descriptor:'#{descriptor}'"
       faxname,faxid = descriptor.split('|')
       if (faxname.nil? or faxid.nil?)
-        logger.info "Valid descriptor not provided to get_fax function call.  Descriptor:'#{descriptor}'"
+        logger.debug "Valid descriptor not provided to get_fax function call.  Descriptor:'#{descriptor}'"
         return nil
       end
 
@@ -182,7 +180,89 @@ module SrFax
       res = execute(postVariables)
       return res
     end
+
+    # Schedules a fax to be sent with or without cover page
+    #
+    # @param faxids [String, Array] Get the state of 'id' as given by the #queue_fax call
+    # @param options [Hash] An optional hash paramter to ovveride any default values (ie., Account ID)
+    # @option options [String] :sResponseFormat The output response format for 
+    # @return [Hash] A hash containing the return value (Success/Failure) and the payload where applicable
+    def get_fax_status(faxids, options = {})
+      logger.debug "Gathering fax status information for id(s):'#{faxids}'"
+
+      if faxids.is_a? String
+        action = "Get_FaxStatus"
+      elsif faxids.is_a? Array
+        action = "Get_MultiFaxStatus"
+        faxids = faxids.join('|')
+      else
+        logger.warn "Error wth fax ids parameter id(s):'#{faxid}'"
+        return { :Status => "Failure" }
+      end
+
+      postVariables = {   
+        :action => action,
+        :sFaxDetailsID => faxids
+      }.merge!(options)
+      res = execute(postVariables)
+      return res
+    end
+
+    # Determines the state of a fax that has been scheduled for delivery.  Use queue fax to schedule a fax
+    # for delivery.  Note: no validation is done on the fields prior to sending.
+    #
+    # @param senderEmail [String] Email address of the sender
+    # @param receiverNumber [String, Array] Single 11 digit fax number or up to 50 x 11 fax numbers
+    # @param faxType [String] 'SINGLE' or 'BROADCAST'
+    # @param options [Hash] An optional hash paramter to ovveride any default values (ie., Account ID)
+    # @option options [String] :sResponseFormat The output response format for 
+    # @option options [String] :sAccountCode Internal reference number (Max of 20 Characters)
+    # @option options [String] :sRetries Number of times the system is to retry a number if busy or an error is encountered – number from 0 to 6.
+    # @option options [String] :sCoverPage If you want to use one of the cover pages on file, specify the cover page you wish to use “Basic”, “Standard” , “Company” or “Personal”. If a cover page is not provided then all cover page variable will be ignored.  NOTE: If the default cover page on the account is set to “Attachments ONLY” the cover page will NOT be created irrespective of this variable.
+    # @option options [String] :sFaxFromHeader From: On the Fax Header Line (max 30 Char)
+    # @option options [String] :sCPFromName Sender’s name on the Cover Page
+    # @option options [String] :sCPToName Recipient’s name on the Cover Page
+    # @option options [String] :sCPOrganization Organization on the Cover Page
+    # @option options [String] :sCPSubject Subject line on the Cover Page**
+    # @option options [String] :sCPComments Comments placed in the body of the Cover Page
+    # @option options [String] :sFileName_x (See supported file types @  https://www.srfax.com/faqs)
+    # @option options [String] :sFileContent_x Base64 encoding of file contents.
+    # @option options [String] :sNotifyURL Provide an absolute URL (beginning with http:// or https://) and the SRFax system will POST back the fax status record when the fax completes. See the ‘NOTIFY URL POST’ section below for details of what is posted.
+    # @return [Hash] A hash containing the return value (Success/Failure) and the payload where applicable  
+    #
+    # Example code (this will send a fax with 'Sample Fax' as the fileContent field):
+    #   SrFax.queue_fax "yourname@yourdomain.com", "SINGLE", "18888888888", {sFileName_1: "file1.txt", sFileContent_1: Base64.encode64("Sample Fax")}
+    def queue_fax(senderEmail, receiverNumber, faxType, options = {})
+      logger.debug "Attempting to queue fax"
+      receiverNumber = receiverNumber.join('|') if receiverNumber.is_a? Array
+
+      postVariables = {   
+        :action => "Queue_Fax",
+        :sSenderEmail => senderEmail,
+        :sFaxType => faxType,
+        :sToFaxNumber => receiverNumber
+      }.merge!(options)
+      res = execute(postVariables)
+      return res
+    end
     
+    # Attempt to stop a fax from being delivered.  See the result payload for possible condiitions in fax status
+    #
+    # @param faxid [String] Stop fax with 'id' as given by the #queue_fax call
+    # @param options [Hash] An optional hash paramter to ovveride any default values (ie., Account ID)
+    # @return [Hash] A hash containing the return value (Success/Failure) and the payload where applicable
+    def stop_fax(faxid, options = {})
+      action = nil 
+      logger.debug "Sending stop fax command for id:'#{faxid}'"
+
+      postVariables = {   
+        :action => 'Stop_Fax',
+        :sFaxDetailsID => faxid
+      }.merge!(options)
+      res = execute(postVariables)
+      return res
+    end
+
     # Delete a particular fax from the SRFax cloud service
     #
     # @param descriptor [String] THe descriptor provided by SRFax which identifies a unique fax
@@ -191,15 +271,13 @@ module SrFax
     #
     # Example Payload for Return: 
     #   {"Status"=>"Success", "Result"=>[{"FileName"=>"20150430124505-6104-19_1|20360095", "ReceiveStatus"=>"Ok", 
-    #   "Date"=>"Apr 30/15 02:45 PM", "EpochTime"=>1430423105, "CallerID"=>"9056193547", "RemoteID"=>"", "Pages"=>"1", 
+    #   "Date"=>"Apr 30/15 02:45 PM", "EpochTime"=>1430423105, "CallerID"=>"5555555555", "RemoteID"=>"", "Pages"=>"1", 
     #   "Size"=>"5000", "ViewedStatus"=>"N"} ]}
-    #  :direction is either 'IN' or 'OUT' for inbox or outbox
-    #  :descriptor is what is returns from the POST Filename field from the view_inbox result
     def delete_fax(descriptor, direction)
-      logger.info "Deleting a fax in the cloud service in the direction of '#{direction}', Descriptor:'#{descriptor}'"
+      logger.debug "Deleting a fax in the cloud service in the direction of '#{direction}', Descriptor:'#{descriptor}'"
       faxname,faxid = descriptor.split('|')
       if (faxname.nil? or faxid.nil?)
-        logger.info "Valid descriptor not provided to get_fax function call.  Descriptor:'#{descriptor}'"
+        logger.debug "Valid descriptor not provided to get_fax function call.  Descriptor:'#{descriptor}'"
         return nil
       end
   
@@ -215,21 +293,22 @@ module SrFax
 
     private
 
-    # Actually execute the RESTful post command to the #BASE_URI
+    # Actually execute the RESTful post command to the #BASE_URL
     #
     # @param postVariables [String] The list of variables to apply in the POST body when executing the request
     # @return [Hash] The hash payload value including a proper status.  Will never return nil.
     def execute(postVariables)
-      res = RestClient::Request.execute :url => BASE_URI, :method => :post, :payload => postVariables.merge(defaults).to_json, :content_type => :json, :accept => :json
+      logger.debug postVariables.merge(defaults)
+      res = RestClient.post BASE_URL, postVariables.merge(defaults).to_json, :content_type => :json, :accept => :json
       return_data = nil
       return_data = JSON.parse(res) if res
 
       if return_data.nil? || return_data.fetch("Status", "Failure") != "Success"
-        logger.info "Execution of SR Fax command not successful" 
-        return_data = { :Status => "Failure" } 
+        logger.debug "Execution of SR Fax command not successful" 
+        return_data = { :Status => "Failure", :Result => return_data.fetch("Result", "") } 
       end
 
-      return return_data
+      return return_data.with_indifferent_access
     end
   end
 end

data/lib/version.rb

@@ -0,0 +1,4 @@
+module SrFax
+  # Version # for SrFax
+  VERSION = '0.4.0'
+end

data/srfax.gemspec

@@ -19,9 +19,11 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "bundler", "~> 1.6"
   spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_runtime_dependency 'logger', '~> 1'
-  spec.add_runtime_dependency 'activesupport', '~> 4.2'
-  spec.add_runtime_dependency 'rest-client', '~> 1.7'
+  spec.add_development_dependency "pry", "~> 0.8"
+  spec.add_development_dependency "yard", "~> 0.8"
+  spec.add_dependency 'logger', '~> 1'
+  spec.add_dependency 'activesupport', '~> 4.2'
+  spec.add_dependency 'rest-client', '~> 1.7'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sr_fax
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Jeff Klink
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-05-12 00:00:00.000000000 Z
+date: 2015-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -17,14 +17,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.7'
+        version: '1.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.7'
+        version: '1.6'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -39,6 +39,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: logger
   requirement: !ruby/object:Gem::Requirement
@@ -97,6 +125,7 @@ files:
 - bin/console
 - bin/setup
 - lib/srfax.rb
+- lib/version.rb
 - srfax.gemspec
 homepage: https://github.com/TechCanuck/srfax
 licenses: