module SrFax

Delete a particular fax from the SRFax cloud service

@param descriptor [String] THe descriptor provided by SRFax which identifies a unique fax @param direction [String] Either 'IN' or 'OUT' to specify the inbox or outbox @return [Hash] A hash containing the return value (Success/Failure) and the payload where applicable

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"=>"5555555555", "RemoteID"=>"", "Pages"=>"1",
"Size"=>"5000", "ViewedStatus"=>"N"} ]}

# File lib/srfax.rb, line 280
def delete_fax(descriptor, direction)
  logger.debug "Deleting a fax in the cloud service in the direction of '#{direction}', Descriptor: '#{descriptor}'"
  faxname, faxid = descriptor.split('|')
  if faxname.nil? || faxid.nil?
    logger.debug "Valid descriptor not provided to get_fax function call. Descriptor: '#{descriptor}'"
    return nil
  end

  postVariables = {
    action: 'Delete_Fax',
    sFaxFileName_x: descriptor,
    sFaxDetailsID_x: faxid,
    sDirection: direction.upcase
  }
  res = execute(postVariables)
  res
end

Uses POST Retrieve_Fax to retrieve a specified fax from the server. Returns it in the default specified format (PDF or TIFF)

@param descriptor [String] Specify the status of the message you are listing (UNREAD, ALL, READ) @param direction [String] Either 'IN' or 'OUT' to specify the inbox or outbox @param options [Hash] An optional hash paramter to ovveride any default values (ie., Account ID) @option options [String] :sMarkasViewed Update the fax status to viewed (or unviewed). Accepts 'Y' or 'N' @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

# File lib/srfax.rb, line 143
def get_fax(descriptor, direction, options = {})
  logger.debug "Retrieving fax from cloud service in the direction of '#{direction}', Descriptor: '#{descriptor}'"
  faxname, faxid = descriptor.split('|')
  if faxname.nil? || faxid.nil?
    logger.debug "Valid descriptor not provided to get_fax function call. Descriptor: '#{descriptor}'"
    return nil
  end

  logger.debug 'Retrieving fax from cloud service'
  postVariables = {
    action: 'Retrieve_Fax',
    sFaxFileName: descriptor,
    sFaxDetailsID: faxid,
    sDirection: direction.upcase,
    sMarkasViewed: 'N'
  }.merge!(options)
  res = execute(postVariables)
  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

# File lib/srfax.rb, line 195
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)
  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 @ 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", "18888888888", "SINGLE", {sFileName_1: "file1.txt", sFileContent_1: Base64.encode64("Sample Fax")}

# File lib/srfax.rb, line 240
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)
  res
end

Allow configuring Srfax with a block, these will be the methods default values for passing to each function and will be overridden by any methods locally posted variables (ex: :action)

@yield Accepts a block of valid configuration options to set or override default values

Example:

Srfax.setup do |config|
  config.defaults[:access_id] = '1234'
  config.defaults[:access_pwd] = 'password'
  config.defaults[:sCallerID] = '5555555555'
end

# File lib/srfax.rb, line 59
def setup
  yield self
end

Attempt to stop a fax from being delivered. See the result payload for possible conditions 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

# File lib/srfax.rb, line 259
def stop_fax(faxid, options = {})
  logger.debug "Sending stop fax command for id: '#{faxid}'"

  postVariables = {
    action: 'Stop_Fax',
    sFaxDetailsID: faxid
  }.merge!(options)
  res = execute(postVariables)
  res
end

Update the status (read/unread) for a particular fax

@param descriptor [String] Specify the status of the message you are listing (UNREAD, ALL, READ) @param direction [String] Either 'IN' or 'OUT' to specify the inbox or outbox @param options [Hash] An optional hash paramter to ovveride any default values (ie., Account ID) @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

# File lib/srfax.rb, line 170
def update_fax_status(descriptor, direction, options = {})
  logger.debug "Updating a fax in the cloud service in the direction of '#{direction}', Descriptor: '#{descriptor}'"
  faxname, faxid = descriptor.split('|')
  if faxname.nil? || faxid.nil?
    logger.debug "Valid descriptor not provided to get_fax function call. Descriptor: '#{descriptor}'"
    return nil
  end

  postVariables = {
    action: 'Update_Viewed_Status',
    sFaxFileName: descriptor,
    sFaxDetailsID: faxid,
    sDirection: direction.upcase,
    sMarkasViewed: 'Y'
  }.merge!(options)
  res = execute(postVariables)
  res
end

Views the remote inbox. By default this call does NOT update the viewed or read status of the fax unless specified in options.

@param status [String] Specify the status of the message you are listing (UNREAD, ALL, READ) @param options [Hash] An optional hash paramter to ovveride any default values (ie., Account ID) @option options [String] :sPeriod Specify the period to query. Accepts 'ALL' or 'RANGE' @option options [String] :sStatDate Used with :sPeriod and denotes the period to start at. Format is 'YYYYMMDD' @option options [String] :sEndDate Used with :sPeriod and denotes the period to endd at. Format is 'YYYYMMDD' @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

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"=>"5555555555", "RemoteID"=>"", "Pages"=>"1",
"Size"=>"5000", "ViewedStatus"=>"N"} ]}

# File lib/srfax.rb, line 78
def view_inbox(status = 'UNREAD', options = {})
  logger.debug 'Checking fax inbox from cloud service'
  postVariables = {
    action: 'Get_Fax_Inbox',
    sViewedStatus: status.upcase
  }.merge!(options)
  res = execute(postVariables)

  if res[:Status] != 'Failure'
    faxcount = res['Result'].length
    faxcount > 0 ? logger.debug("Found #{faxcount} new fax(es)") : logger.debug('No faxes found matching that criteria')
  end

  res
end

Uses post Get_Fax_Outbox to retrieve the usage for the account (and all subaccounts)

@param options [Hash] An optional hash paramter to ovveride any default values (ie., Account ID) @option options [String] :sPeriod Specify the period to query. Accepts 'ALL' or 'RANGE' @option options [String] :sStatDate Used with :sPeriod and denotes the period to start at. Format is 'YYYYMMDD' @option options [String] :sEndDate Used with :sPeriod and denotes the period to endd at. Format is 'YYYYMMDD' @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

# File lib/srfax.rb, line 121
def view_outbox(options = {})
  logger.debug 'Viewing fax outbox from cloud service'
  postVariables = { action: 'Get_Fax_Outbox' }
  res = execute(postVariables)

  if res[:Status] != 'Failure'
    faxcount = res['Result'].length
    faxcount > 0 ? logger.debug("Found #{faxcount} new fax(es)") : logger.debug('No faxes found matching that criteria')
  end

  res
end

Uses post Get_Usage to fetch the current account usage statistics (for all associated accounts)

@param options [Hash] An optional hash paramter to ovveride any default values (ie., Account ID) @option options [String] :sPeriod Specify the period to query. Accepts 'ALL' or 'RANGE' @option options [String] :sStatDate Used with :sPeriod and denotes the period to start at. Format is 'YYYYMMDD' @option options [String] :sEndDate Used with :sPeriod and denotes the period to endd at. Format is 'YYYYMMDD' @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

Example Payload for Return:

{"Status"=>"Success", "Result"=>[{"UserID"=>1234, "Period"=>"ALL",
"ClientName"=>nil, "SubUserID"=>0, "BillingNumber"=>"8888888888", "NumberOfFaxes"=>5, "NumberOfPages"=>8}]}

# File lib/srfax.rb, line 106
def view_usage(options = {})
  logger.debug 'Viewing fax usage from cloud service'
  postVariables = { action: 'Get_Fax_Usage' }
  res = execute(postVariables)
  res
end

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.

# File lib/srfax.rb, line 304
def execute(postVariables)
  logger.debug postVariables.merge(defaults)
  # Redirect where necessary.
  res = RestClient.post(BASE_URL, postVariables.merge(defaults), { accept: :json })
  unless res.code == 200
    return { 'Status' => 'Failed', 'Result' => res.body }.with_indifferent_access
  end

  return_data = JSON.parse(res.body).with_indifferent_access

  if return_data['Status'] == 'Failed'
    logger.debug 'Execution of SR Fax command not successful'
  end
  return_data
end