faxage 1.0.0 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ddc13458c6a5240635be1aa1f7c8e7aec3e794121f399fb7b985aa426c72c44
-  data.tar.gz: 226ad755e313625fa171771ea213e3d2a7b1333f702c01ff14763939274cebb5
+  metadata.gz: f9b7534be52991e73089c5258d35d4cd791c2fbd7370c1a005946bb292f3b940
+  data.tar.gz: 076cb60e728a22f1bd7c7b98c761abfcb3c8ec572fb4b041f642260970ff3014
 SHA512:
-  metadata.gz: ad8704196cd2d4f200d4258d21546436287057a5318164899e376b139bdd987c1bdbb1e8cbc792630683c2a4442483ae02ecbfdd3cae4f83f2de7be018792190
-  data.tar.gz: 233e11214f064bc0b6901a595af546462fc6b9d4c546caa080792c5b7007ce8c420c35531bf488cf9c3ff06805b6662153bf44889c05a8461bfe62107ae32b89
+  metadata.gz: 82aa232fd6cdc0ae82adae99df8b661b365c2d27bc66475f0cea96cca5ac89af3a191298618ddd356ac029b1f994ca0328e787e7d720bca735a98dff90c48ebb
+  data.tar.gz: 9b683d9d4de97e2eda7d36953aa9fa96ac1274342f033f5deccbdb1f2927249f60994864affa1855f45936d9e44978e94db348561e0290f9a9ce43fa265d4918

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    faxage (1.0.0)
+    faxage (1.2.2)
       httparty
 
 GEM
@@ -40,4 +40,4 @@ DEPENDENCIES
   rspec (>= 3.4)
 
 BUNDLED WITH
-   1.17.1
+   2.1.4

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/information_gathering.rb

@@ -293,5 +293,40 @@ module Faxage
         return response.parsed_response
       end
     end
+
+    def dlstatus(jobid:, viewtype: 'pdf')
+      # This operation is used to download a sent fax image.
+
+      subdirectory = "/httpsfax.php"
+
+      body = {
+        operation: "dlstatus",
+        username: username,
+        company: company,
+        password: password,
+        jobid: jobid,
+        viewtype: viewtype
+      }
+
+      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?("ERR06: No jobs to display or job id specified not found")
+        raise InvalidJobIdError.new("The jobid you passed was not found")
+      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?("ERR24: File is not yet converted")
+        raise NoFilesError.new("Images can only be retrieved after the file(s) have actually been imaged (I.e.: The fax must either be In Queue or completed to be able to retrieve an image)")
+      elsif response.parsed_response.include?("ERR25: File does not exist")
+        raise NoFilesError.new("This can be either an internal error, or if the status is a ‘Failed Conversion’, then there is no image to retrieve")
+      else
+        return response.parsed_response
+      end
+    end
   end
-end
+end

data/lib/faxage/receive_fax.rb

@@ -7,7 +7,7 @@ module Faxage
 
     attr_reader :username, # Assigned FAXAGE username
                 :company, # Assigned FAXAGE company credential
-                :password, # Assigned FAXAGE password
+                :password # Assigned FAXAGE password
 
     def initialize(username:, company:, password:)
       @username = username
@@ -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
@@ -42,7 +76,70 @@ module Faxage
       elsif response.parsed_response.include?("ERR11: No incoming faxes available")
         raise NoIncomingFaxesError.new("There are no incoming faxes to list for you.")
       else
-        return response.parsed_response
+        data = []
+        response.parsed_response.split("\n").each do |received_fax|
+          # <recvid><tab><recvdate>(OPTIONAL:
+          # <tab><starttime>)
+          # <tab><CID><tab><DNIS>(OPTIONAL:
+          # <tab><filename>)(OPTIONAL:
+          # <tab><pagecount>)(OPTIONAL: <tab><tsid>)
+          individual_fax = Hash.new
+          received_fax.split("\t").each_with_index do |item, index|
+            if options[:starttime].nil?
+              if index == 0
+                individual_fax[:recvid] = item
+              elsif index == 1
+                individual_fax[:revdate] = item
+              elsif index == 2
+                individual_fax[:cid] = item
+              elsif index == 3
+                individual_fax[:dnis] = item
+              elsif index == 4 && !options[:filename].nil?
+                individual_fax[:filename] = item
+              elsif index == 4 && options[:filename].nil? && !options[:pagecount].nil?
+                individual_fax[:pagecount] = item
+              elsif index == 4 && options[:filename].nil? && options[:pagecount].nil? && !options[:showtsid].nil?
+                individual_fax[:tsid] = item
+              elsif index == 5 && !options[:filename].nil? && !options[:pagecount].nil?
+                individual_fax[:pagecount] = item
+              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
+              elsif index == 6 && !options[:filename].nil? && !options[:pagecount].nil? && !options[:showtsid].nil?
+                individual_fax[:tsid] = item
+              end
+            else
+              if index == 0
+                individual_fax[:recvid] = item
+              elsif index == 1
+                individual_fax[:revdate] = item
+              elsif index == 2
+                individual_fax[:starttime] = item
+              elsif index == 3
+                individual_fax[:cid] = item
+              elsif index == 4
+                individual_fax[:dnis] = item
+              elsif index == 5 && !options[:filename].nil?
+                individual_fax[:filename] = item
+              elsif index == 5 && options[:filename].nil? && !options[:pagecount].nil?
+                individual_fax[:pagecount] = item
+              elsif index == 5 && options[:filename].nil? && options[:pagecount].nil? && !options[:showtsid].nil?
+                individual_fax[:tsid] = item
+              elsif index == 6 && !options[:filename].nil? && !options[:pagecount].nil?
+                individual_fax[:pagecount] = item
+              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
+              elsif index == 7 && !options[:filename].nil? && !options[:pagecount].nil? && !options[:showtsid].nil?
+                individual_fax[:tsid] = item
+              end
+            end
+            data << individual_fax
+          end
+        end
+        return data
       end
     end
   end

data/lib/faxage/version.rb

@@ -1,3 +1,3 @@
 module Faxage
-  VERSION = "1.0.0"
+  VERSION = "1.2.2"
 end

data/lib/faxage.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: faxage
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.2
 platform: ruby
 authors:
 - Kevin Dias
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-03-05 00:00:00.000000000 Z
+date: 2022-01-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -98,7 +98,7 @@ homepage: https://github.com/diasks2/faxage
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -113,9 +113,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
-signing_key: 
+rubygems_version: 3.1.6
+signing_key:
 specification_version: 4
 summary: Faxage is a Ruby wrapper for the faxage.com API
 test_files: []