faxage 0.1.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd31e18b35891cb250ccb07aae95a8ed770cafb932a416b5098791d6e6bd6745
-  data.tar.gz: 411dda5041bdec000fc53c0874338fb227b84669b449f955b9c83c67c4497acc
+  metadata.gz: 9ddc13458c6a5240635be1aa1f7c8e7aec3e794121f399fb7b985aa426c72c44
+  data.tar.gz: 226ad755e313625fa171771ea213e3d2a7b1333f702c01ff14763939274cebb5
 SHA512:
-  metadata.gz: 72ca783e4cae038b68443b62fc8f92909b63f0f76cb2dac08f51d756c9a8a6c1bc853563fe9479b4ca3a1fc28a50f038c44fc89b552f771b4325b722fb63a119
-  data.tar.gz: b6a79eeaf114f00137fa837f8b623cb42624991babc5b23ada98f93f08bc89ebbf641cf4b698525dadeef02ed5eb21f0c8db8d398f910c041236f66b83a719f8
+  metadata.gz: ad8704196cd2d4f200d4258d21546436287057a5318164899e376b139bdd987c1bdbb1e8cbc792630683c2a4442483ae02ecbfdd3cae4f83f2de7be018792190
+  data.tar.gz: 233e11214f064bc0b6901a595af546462fc6b9d4c546caa080792c5b7007ce8c420c35531bf488cf9c3ff06805b6662153bf44889c05a8461bfe62107ae32b89

data/Gemfile.lock

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

data/README.md

@@ -57,7 +57,13 @@ Click the link for ‘Q: What types of files can I send?’ on the above URL to
 | Plain Text                           | TXT          |
 
 #### Sending a fax
+
+##### sendfax
+
+This operation is used to send a fax.
+
 ```ruby
+
 Faxage::SendFax.new(
   username: # Assigned FAXAGE username
   company: # Assigned FAXAGE company credential
@@ -77,8 +83,45 @@ Faxage::SendFax.new(
   # regular/production URL.
   # For example, if you send a fax using the sendfax operation with
   # the debugging URL, the fax will still get sent as normal.
-).send_fax()
+).sendfax()
+
+# Practical example of faxing a template from your Rails app:
+# html = ActionController::Base.new().render_to_string(template: 'path-to-your-template')
+# encoded_file_data = Base64.encode64(html)
+
+Faxage::SendFax.new(
+  username: "your-username", # string
+  company: "your-faxage-company-id", # string
+  password: "your-faxage-password", # string
+  recipname: "ABC company", #string
+  faxno: "5555555555", # string (no hyphens, parenthesis, or spaces)
+  faxfilenames: ['my-file.html'],
+  faxfiledata: [encoded_file_data],
+  debug: false
+).sendfax()
+
+# Expected response:
+
+# {
+#   job_id: 543211
+# }
+
+
+```
+
+#### Receiving a fax
+
+##### listfax
+This operation is used to gather a list of incoming faxes for your account.
+
+```ruby
+Faxage::ReceiveFax.new(
+  username: # Assigned FAXAGE username
+  company: # Assigned FAXAGE company credential
+  password: # Assigned FAXAGE password
+).listfax()
 ```
+
 #### Information Gathering Operations
 
 These operations relate to gathering information that helps with managing and/or
@@ -101,6 +144,83 @@ Faxage::InformationGathering.new(
 # }
 ```
 
+##### pendcount
+This operation allows you to see how many outgoing faxes are currently pending to be sent on your FAXAGE account.
+
+```ruby
+Faxage::InformationGathering.new(
+  username: # Assigned FAXAGE username
+  company: # Assigned FAXAGE company credential
+  password: # Assigned FAXAGE password
+).pendcount
+
+# Example response:
+# {
+#   pending_count: 10
+# }
+```
+
+##### qstatus
+This operation allows you to gather details about how your outgoing pending faxes are currently queued. When you have more than one line on your FAXAGE account, the system automatically load-levels outgoing faxes across however many lines you have. Using this operation, you can see all of your pending outgoing faxes and which line(s) they are queued on, in order to analyze how your outgoing traffic is being distributed for sending by FAXAGE.
+
+```ruby
+Faxage::InformationGathering.new(
+  username: # Assigned FAXAGE username
+  company: # Assigned FAXAGE company credential
+  password: # Assigned FAXAGE password
+).qstatus
+```
+
+##### incomingcalls
+This operation allows you to see how many incoming calls are currently in progress to your account and how many maximum total simultaneous calls your account is currently configured to allow without sending a busy signal.
+
+```ruby
+Faxage::InformationGathering.new(
+  username: # Assigned FAXAGE username
+  company: # Assigned FAXAGE company credential
+  password: # Assigned FAXAGE password
+).incomingcalls
+
+# Example response:
+# {
+#   incoming_count: 0,
+#   allocated_count: 1
+# }
+```
+
+##### busycalls
+This operation allows you to see incoming calls that have experienced a busy signal because more calls were in progress at the time the call came than your account was configured to support.
+
+```ruby
+Faxage::InformationGathering.new(
+  username: # Assigned FAXAGE username
+  company: # Assigned FAXAGE company credential
+  password: # Assigned FAXAGE password
+).busycalls
+```
+
+##### portstatus
+This operation allows you to see the status of port requests you have in progress or that have been completed with FAXAGE.
+
+```ruby
+Faxage::InformationGathering.new(
+  username: # Assigned FAXAGE username
+  company: # Assigned FAXAGE company credential
+  password: # Assigned FAXAGE password
+).portstatus
+```
+
+##### auditlog
+This operation allows you to retrieve audit logs for your FAXAGE account. The FAXAGE auditing system is a comprehensive system that keeps a trail of all activities within your account. See the FAXAGE Internet Fax Auditing Documentation for details as to the structure of audit logs and what data is contained within each type of auditable operation.
+
+```ruby
+Faxage::InformationGathering.new(
+  username: # Assigned FAXAGE username
+  company: # Assigned FAXAGE company credential
+  password: # Assigned FAXAGE password
+).auditlog
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/faxage.gemspec

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 
 lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)

data/lib/faxage.rb

@@ -1,5 +1,6 @@
 require "faxage/version"
 require "faxage/send_fax"
+require "faxage/receive_fax"
 require "faxage/information_gathering"
 
 class LoginError < StandardError
@@ -24,4 +25,7 @@ class NoFilesError < StandardError
 end
 
 class BlockedNumberError < StandardError
+end
+
+class NoIncomingFaxesError < StandardError
 end

data/lib/faxage/information_gathering.rb

@@ -8,6 +8,7 @@ module Faxage
     attr_reader :username, # Assigned FAXAGE username
                 :company, # Assigned FAXAGE company credential
                 :password # Assigned FAXAGE password
+
     def initialize(username:, company:, password:)
       @username = username
       @company = company
@@ -37,7 +38,7 @@ module Faxage
       elsif response.parsed_response.include?("ERR01: Database connection failed")
         raise FaxageInternalError.new("Internal FAXAGE error.")
       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.")
+        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}")
       else
         parsed_response = response.parsed_response.gsub("\n", "").split("~")
         data = {
@@ -72,7 +73,7 @@ module Faxage
       elsif response.parsed_response.include?("ERR01: Database connection failed")
         raise FaxageInternalError.new("Internal FAXAGE error.")
       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.")
+        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}")
       else
         parsed_response = response.parsed_response.gsub("\n", "").to_i
         data = {
@@ -109,7 +110,7 @@ module Faxage
       elsif response.parsed_response.include?("ERR01: Database connection failed")
         raise FaxageInternalError.new("Internal FAXAGE error.")
       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.")
+        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}")
       else
         # TODO - parse response
 
@@ -154,7 +155,7 @@ module Faxage
       elsif response.parsed_response.include?("ERR01: Database connection failed")
         raise FaxageInternalError.new("Internal FAXAGE error.")
       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.")
+        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}")
       else
         parsed_response = response.parsed_response.gsub("\n", "").split("~")
         data = {
@@ -190,7 +191,7 @@ module Faxage
       elsif response.parsed_response.include?("ERR01: Database connection failed")
         raise FaxageInternalError.new("Internal FAXAGE error.")
       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.")
+        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}")
       else
         # TODO - parse response
 
@@ -229,7 +230,7 @@ module Faxage
       elsif response.parsed_response.include?("ERR01: Database connection failed")
         raise FaxageInternalError.new("Internal FAXAGE error.")
       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.")
+        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}")
       else
         # TODO - parse response
 
@@ -279,7 +280,7 @@ module Faxage
       elsif response.parsed_response.include?("ERR01: Database connection failed")
         raise FaxageInternalError.new("Internal FAXAGE error.")
       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.")
+        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}")
       else
         # TODO - parse response
 

data/lib/faxage/receive_fax.rb

@@ -0,0 +1,49 @@
+require 'httparty'
+
+module Faxage
+  class ReceiveFax
+    include HTTParty
+    base_uri "https://api.faxage.com"
+
+    attr_reader :username, # Assigned FAXAGE username
+                :company, # Assigned FAXAGE company credential
+                :password, # Assigned FAXAGE password
+
+    def initialize(username:, company:, password:)
+      @username = username
+      @company = company
+      @password = password
+    end
+
+    def listfax(**options)
+      # This operation is used to gather a list of incoming faxes for your account.
+
+      subdirectory = "/httpsfax.php"
+
+      body = {
+        operation: "listfax",
+        username: username,
+        company: company,
+        password: password
+      }.merge!(options)
+
+      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?("ERR11: No incoming faxes available")
+        raise NoIncomingFaxesError.new("There are no incoming faxes to list for you.")
+      else
+        return response.parsed_response
+      end
+    end
+  end
+end

data/lib/faxage/send_fax.rb

@@ -35,7 +35,7 @@ module Faxage
       @debug = debug
     end
 
-    def send_fax(**options)
+    def sendfax(**options)
       if debug
         subdirectory = "/httpsfax-debug.php"
       else
@@ -70,14 +70,22 @@ module Faxage
       elsif response.parsed_response.include?("ERR05")
         raise BlockedNumberError.new("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).")
       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.")
+        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?("ERR15: Invalid Job ID")
         raise InvalidJobIdError.new("Internal FAXAGE error – the job was not properly inserted into our database.")
       else
+        debug_output = response.parsed_response
         job_id = response.parsed_response.scan(JOB_ID_REGEX)[0].strip.to_i
-        data = {
-          job_id: job_id
-        }
+        if debug
+          data = {
+            job_id: job_id,
+            debug: debug_output
+          }
+        else
+          data = {
+            job_id: job_id
+          }
+        end
         return data
       end
     end

data/lib/faxage/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: faxage
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 1.0.0
 platform: ruby
 authors:
 - Kevin Dias
@@ -91,6 +91,7 @@ files:
 - faxage.gemspec
 - lib/faxage.rb
 - lib/faxage/information_gathering.rb
+- lib/faxage/receive_fax.rb
 - lib/faxage/send_fax.rb
 - lib/faxage/version.rb
 homepage: https://github.com/diasks2/faxage