faxage 1.1.1 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cef925b012340a06484d13804bef6028f9e6947c545c5a704e2c7b7d4b68e278
-  data.tar.gz: 8aa2da77601b18e6b8fad5f0c0a335e49109fcbd6af028453bd296499639bfd1
+  metadata.gz: 7a03e5a557de75e3e23b481552f7dac9d652496ca6a013978c51580f3b88c50d
+  data.tar.gz: ce9c8db7811d2c0f587aef771d6a425d4b465f5822f2da339059197524819a52
 SHA512:
-  metadata.gz: 05417c5b676dd0b6c7e547bb7f2a96743cd096c7304537f6f463582c5babbd01f644eb011e445734c5b473cf0ef12fa1e4d5e46d924f639a1519672bba7c8174
-  data.tar.gz: b68dd6c22a01c949a6140688628047c7a069f3be85b2e718634fbb6d39afe40df8ff1f28a883d966c9ac508c728aba6379db21e74ebd9685dd89abd78f9d108a
+  metadata.gz: 051ae752d2f1e6a3a8d17df6e3b7c8cefda75c242a846e7619f704cc46ce7637e0483d3ba5c6ed83c5c483b6b5cc73f2d4b7873c420b827ec310b7d23882f7a7
+  data.tar.gz: 14eaa675be8861717f7bf9596703adba1a2b8549e1c0e731f9db6980e26bcf661e7cbc8d7dc914f8c1e10b0c201f9255745d535cb868575fb873c11e6f85bb9e

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    faxage (1.1.1)
+    faxage (1.2.1)
       httparty
 
 GEM

data/README.md

@@ -56,6 +56,51 @@ Click the link for ‘Q: What types of files can I send?’ on the above URL to
 | HP Printer Control Language          | PCL          |
 | Plain Text                           | TXT          |
 
+#### Error Types
+
+```ruby
+class LoginError < StandardError
+  # "One or more of username, company, password is incorrect or your account is disabled for some reason."
+end
+
+class FaxageInternalError < StandardError
+  # "Internal FAXAGE error."
+end
+
+class UnknownOperationError < StandardError
+  # "Either operation is not correctly hard coded or the POST was bad, the POST contents are returned for debugging purposes. #{response.parsed_response}"
+end
+
+class NoResponseError < StandardError
+  # "An empty response was returned from Faxage."
+end
+
+class InvalidJobIdError < StandardError
+  # "Internal FAXAGE error – the job was not properly inserted into our database."
+end
+
+class InvalidFaxNoError < StandardError
+  # "The faxno variable does not contain a 10-digit numeric only string."
+end
+
+class NoFilesError < StandardError
+  # "No valid files were found in faxfilenames[] and/or faxfiledata[]."
+end
+
+class BlockedNumberError < StandardError
+  # "The number you tried to fax to was blocked (outside of continental US, Canada and Hawaii or a 555, 911, or other invalid/blocked type of number)."
+end
+
+class NoIncomingFaxesError < StandardError
+  # "There are no incoming faxes to list for you."
+end
+
+class FaxIdNotFoundError < StandardError
+  # The faxid passed in is invalid or is an ID that does not belong to your company.
+end
+```
+
+
 #### Sending a fax
 
 ##### sendfax
@@ -122,6 +167,32 @@ Faxage::ReceiveFax.new(
 ).listfax()
 ```
 
+##### getfax
+This operation is used to download a received fax image.
+```ruby
+Faxage::ReceiveFax.new(
+  username: # Assigned FAXAGE username
+  company: # Assigned FAXAGE company credential
+  password: # Assigned FAXAGE password
+).getfax(recvid:) # The numeric ID of the fax to get, retrieved from the listfax operation (the recvid in listfax)
+
+# The actual data returned will be the binary contents of the fax itself.
+
+# A practical example of uploading the file to AWS S3 in a Rails application could look like:
+
+get_fax = Faxage::ReceiveFax.new(
+  username: # Assigned FAXAGE username
+  company: # Assigned FAXAGE company credential
+  password: # Assigned FAXAGE password
+).getfax(recvid:)
+
+creds = Aws::Credentials.new(ENV['AWS_ACCESS_KEY_ID'], ENV['AWS_SECRET_ACCESS_KEY'])
+s3_resource = Aws::S3::Resource.new(region: ENV['AWS_S3_REGION'], credentials: creds)
+obj = s3_resource.bucket(ENV['AWS_BUCKET_NAME']).object("path-to-your-file-on-S3/your-file-name.pdf")
+obj.put(body: get_fax)
+
+```
+
 #### Information Gathering Operations
 
 These operations relate to gathering information that helps with managing and/or

data/lib/faxage.rb

@@ -28,4 +28,7 @@ class BlockedNumberError < StandardError
 end
 
 class NoIncomingFaxesError < StandardError
+end
+
+class FaxIdNotFoundError < StandardError
 end

data/lib/faxage/receive_fax.rb

@@ -15,6 +15,40 @@ module Faxage
       @password = password
     end
 
+    def getfax(recvid:, **options)
+      # This operation is used to download a received fax image.
+
+      subdirectory = "/httpsfax.php"
+
+      body = {
+        operation: "getfax",
+        username: username,
+        company: company,
+        password: password,
+        faxid: recvid
+      }.merge!(options.each { |k, v| options[k] = 1 if v } )
+
+      response = self.class.post(subdirectory,
+        body: body
+      )
+
+      if response.parsed_response.nil?
+        raise NoResponseError.new("An empty response was returned from Faxage.")
+      elsif response.parsed_response.include?("ERR01: Database connection failed")
+        raise FaxageInternalError.new("Internal FAXAGE error.")
+      elsif response.parsed_response.include?("ERR02: Login incorrect")
+        raise LoginError.new("One or more of username, company, password is incorrect or your account is disabled for some reason.")
+      elsif response.parsed_response.include?("ERR08: Unknown operation")
+        raise UnknownOperationError.new("Either operation is not correctly hard coded or the POST was bad, the POST contents are returned for debugging purposes. #{response.parsed_response}")
+      elsif response.parsed_response.include?("ERR12: FAX ID")
+        raise FaxIdNotFoundError.new("The faxid passed in is invalid or is an ID that does not belong to your company. #{response.parsed_response}")
+      elsif response.parsed_response.include?("ERR13: File could not be opened")
+        raise FaxageInternalError.new("Internal FAXAGE error. #{response.parsed_response}.")
+      else
+        return response.parsed_response
+      end
+    end
+
     def listfax(**options)
       # This operation is used to gather a list of incoming faxes for your account.
 
@@ -25,7 +59,7 @@ module Faxage
         username: username,
         company: company,
         password: password
-      }.merge!(options)
+      }.merge!(options.each { |k, v| options[k] = 1 if v } )
 
       response = self.class.post(subdirectory,
         body: body
@@ -52,51 +86,53 @@ module Faxage
           individual_fax = Hash.new
           received_fax.split("\t").each_with_index do |item, index|
             if options[:starttime].nil?
-              case index
-              when 0
+              if index == 0
                 individual_fax[:recvid] = item
-              when 1
+              elsif index == 1
                 individual_fax[:revdate] = item
-              when 2
+              elsif index == 2
                 individual_fax[:cid] = item
-              when 3
+              elsif index == 3
                 individual_fax[:dnis] = item
-              when 4 && !options[:filename].nil?
+              elsif index == 4 && !options[:filename].nil?
                 individual_fax[:filename] = item
-              when 4 && options[:filename].nil? && !options[:pagecount].nil?
+              elsif index == 4 && options[:filename].nil? && !options[:pagecount].nil?
                 individual_fax[:pagecount] = item
-              when 4 && options[:filename].nil? && options[:pagecount].nil? && !options[:tsid].nil?
+              elsif index == 4 && options[:filename].nil? && options[:pagecount].nil? && !options[:showtsid].nil?
                 individual_fax[:tsid] = item
-              when 5 && !options[:filename].nil? && !options[:pagecount].nil?
+              elsif index == 5 && !options[:filename].nil? && !options[:pagecount].nil?
                 individual_fax[:pagecount] = item
-              when 5 && !options[:filename].nil? && options[:pagecount].nil? && !options[:tsid].nil?
+              elsif index == 5 && !options[:filename].nil? && options[:pagecount].nil? && !options[:showtsid].nil?
+                individual_fax[:tsid] = item
+              elsif index == 5 && options[:filename].nil? && !options[:pagecount].nil? && !options[:showtsid].nil?
                 individual_fax[:tsid] = item
-              when 6 && !options[:filename].nil? && !options[:pagecount].nil? && !options[:tsid].nil?
+              elsif index == 6 && !options[:filename].nil? && !options[:pagecount].nil? && !options[:showtsid].nil?
                 individual_fax[:tsid] = item
               end
             else
-              case index
-              when 0
+              if index == 0
                 individual_fax[:recvid] = item
-              when 1
+              elsif index == 1
                 individual_fax[:revdate] = item
-              when 2
+              elsif index == 2
                 individual_fax[:starttime] = item
-              when 3
+              elsif index == 3
                 individual_fax[:cid] = item
-              when 4
+              elsif index == 4
                 individual_fax[:dnis] = item
-              when 5 && !options[:filename].nil?
+              elsif index == 5 && !options[:filename].nil?
                 individual_fax[:filename] = item
-              when 5 && options[:filename].nil? && !options[:pagecount].nil?
+              elsif index == 5 && options[:filename].nil? && !options[:pagecount].nil?
                 individual_fax[:pagecount] = item
-              when 5 && options[:filename].nil? && options[:pagecount].nil? && !options[:tsid].nil?
+              elsif index == 5 && options[:filename].nil? && options[:pagecount].nil? && !options[:showtsid].nil?
                 individual_fax[:tsid] = item
-              when 6 && !options[:filename].nil? && !options[:pagecount].nil?
+              elsif index == 6 && !options[:filename].nil? && !options[:pagecount].nil?
                 individual_fax[:pagecount] = item
-              when 6 && !options[:filename].nil? && options[:pagecount].nil? && !options[:tsid].nil?
+              elsif index == 6 && !options[:filename].nil? && options[:pagecount].nil? && !options[:showtsid].nil?
+                individual_fax[:tsid] = item
+              elsif index == 6 && options[:filename].nil? && !options[:pagecount].nil? && !options[:showtsid].nil?
                 individual_fax[:tsid] = item
-              when 7 && !options[:filename].nil? && !options[:pagecount].nil? && !options[:tsid].nil?
+              elsif index == 7 && !options[:filename].nil? && !options[:pagecount].nil? && !options[:showtsid].nil?
                 individual_fax[:tsid] = item
               end
             end

data/lib/faxage/version.rb

@@ -1,3 +1,3 @@
 module Faxage
-  VERSION = "1.1.1"
+  VERSION = "1.2.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: faxage
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.1
 platform: ruby
 authors:
 - Kevin Dias