sr_fax 0.2.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 56a3f8e6fc0de9b9777780d6a53e07b0321d8dcc
+  data.tar.gz: a0a385e62d210e72b916e66bc2607855074333d1
+SHA512:
+  metadata.gz: 255ad2006904e751d180537d21de052a0038ee23d47405bd446f7e8d9eac9e83e395f3dc20b464972c2a2f6a290eb5ce1815c377861594b9b2a52dd020e8a0ce
+  data.tar.gz: 6baffe09500daa159d920a1c6bcd088faf3c3c08310441b0c9f089aa2687379777c45629a9316119b1e45c21004caa751d0589f77f2d9397749eed1fc6b403f7

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+gemfiles/*.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.gem

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Sean Esson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,68 @@
+Srfax
+
+This is the 'unofficial' SRFax (http://www.srfax.com) API wrapper for ruby.  The API documentation for SRFax can be found at https://www.srfax.com/srf/media/SRFax-REST-API-Documentation.pdf
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'sr_fax'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself using: 
+
+    $ gem install sr_fax
+
+## Usage
+
+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
+
+require 'SrFax'
+
+SrFax.setup do |config|
+  config.defaults[:access_id] = '1234'
+  config.defaults[:access_pwd] = 'password'
+end
+
+SrFax.view_inbox
+SrFax.view_outbox
+SrFax.update_fax_status(descriptor, direction) 
+SrFax.get_fax(descriptor, direction, {:sMarkasViewed => 'Y'} 
+```
+
+The SrFax module currently supports the following functions
+  - Sending and receiving faxes
+  - Updating flags on the inbox or outbox faxes
+  - Deleting faxes from either the inbox or outbox
+  - View account usage
+  - Download faxes from the inbox or outbox
+
+Not yet implemented:
+  - Sending faxes
+  - Delete pending faxes (to be sent)
+  - Stop fax
+  - Multifax status
+
+## Development
+
+After checking out the repo, run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+1. Fork it ( https://github.com/TechCanuck/srfax/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+Licensing: **MIT**  
+Remember: **'Great opportunities to help others seldom come, but small ones surround us daily' -- Sally Koch**

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+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.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/srfax.rb

@@ -0,0 +1,236 @@
+require 'RestClient'
+require 'active_support'
+
+# 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.  
+#
+# This module currently Implements the following POST commands from the API:
+#  Get_Usage – Retrieves the account usage
+#  Update_Viewed_Status – Mark a inbound or outbound fax as read or unread.
+#  Queue_Fax - Schedules a fax to be sent with or without cover page.
+#  Get_Fax_Inbox - Returns a list of faxes received for a specified period of time
+#  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
+module SrFax
+  VERSION = '0.3.0pre'
+
+  # Base URL for accessing SRFax API
+  BASE_URI = "https://www.srfax.com/SRF_SecWebSvc.php"
+
+  mattr_accessor :defaults
+  # Default values hash to use with all #execute commands
+  @@defaults = {
+    access_id: '1234',
+    access_pwd: 'password',
+    sFaxFormat: 'PDF', # Default format, PDF or TIF
+    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)
+
+  class << self
+    # 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'
+    #   end
+    def setup(&block)
+      yield self
+    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"=>"9056193547", "RemoteID"=>"", "Pages"=>"1", 
+    #   "Size"=>"5000", "ViewedStatus"=>"N"} ]}
+    def view_inbox(status = 'UNREAD', options = {})
+      logger.info("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"].count
+        faxcount > 0 ? logger.debug("Found #{faxcount} new fax(es)") : logger.debug("No faxes found matching that criteria")
+      end
+  
+      return 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"=>"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)
+    def view_usage(options = {})
+      logger.info "Viewing fax usage from cloud service"
+      postVariables = { :action => "Get_Fax_Usage" }
+      res = execute(postVariables)
+      return 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
+    def view_outbox(options = {})
+      logger.info "Viewing fax outbox from cloud service"
+      postVariables = { :action => "Get_Fax_Outbox" }
+      res = execute(postVariables)
+  
+      if res[:Status] != "Failure"
+        faxcount = res["Result"].count
+        faxcount > 0 ? logger.debug("Found #{faxcount} new fax(es)") : logger.debug("No faxes found matching that criteria")
+      end
+  
+      return 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
+    def get_fax(descriptor, direction, options = {}) 
+      logger.info "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}'"
+        return nil
+      end
+  
+      logger.info "Retrieving fax from cloud service"
+      postVariables = {   
+        :action => "Retrieve_Fax",
+        :sFaxFileName => descriptor,
+        :sFaxDetailsID => faxid,
+        :sDirection => direction.upcase, 
+        :sMarkasViewed => 'N'
+      }.merge!(options)
+      res = execute(postVariables)
+      return 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
+    def update_fax_status(descriptor, direction, options = {})
+      logger.info "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}'"
+        return nil
+      end
+
+      postVariables = {   
+        :action => "Update_Viewed_Status",
+        :sFaxFileName => descriptor,
+        :sFaxDetailsID => faxid,
+        :sDirection => direction.upcase, 
+        :sMarkasViewed => 'Y',
+      }.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
+    # @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"=>"9056193547", "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}'"
+      faxname,faxid = descriptor.split('|')
+      if (faxname.nil? or faxid.nil?)
+        logger.info "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)
+      return res
+    end
+
+    private
+
+    # Actually execute the RESTful post command to the #BASE_URI
+    #
+    # @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
+      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" } 
+      end
+
+      return return_data
+    end
+  end
+end
+

data/srfax.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'version.rb'
+
+Gem::Specification.new do |spec|
+  spec.name          = "sr_fax"
+  spec.version       = SrFax::VERSION
+  spec.authors       = ["Jeff Klink", "Sean Esson"]
+  spec.email         = ["techcanuck@gmail.com"]
+
+  spec.summary       = %q{SR Fax Module provides and easy way to access SR fax online services to send, receive or query faxes}
+  spec.description   = %q{This is the 'unofficial' SRFax (http://www.srfax.com) API wrapper for ruby.  The API documentation for SRFax can be found at https://www.srfax.com/srf/media/SRFax-REST-API-Documentation.pdf}
+  spec.homepage      = "https://github.com/TechCanuck/srfax"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  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 "rake", "~> 10.0"
+  spec.add_runtime_dependency 'logger', '~> 1'
+  spec.add_runtime_dependency 'activesupport', '~> 4.2'
+  spec.add_runtime_dependency 'rest-client', '~> 1.7'
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: sr_fax
+version: !ruby/object:Gem::Version
+  version: 0.2.2
+platform: ruby
+authors:
+- Jeff Klink
+- Sean Esson
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-05-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+description: This is the 'unofficial' SRFax (http://www.srfax.com) API wrapper for
+  ruby.  The API documentation for SRFax can be found at https://www.srfax.com/srf/media/SRFax-REST-API-Documentation.pdf
+email:
+- techcanuck@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/srfax.rb
+- srfax.gemspec
+homepage: https://github.com/TechCanuck/srfax
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: SR Fax Module provides and easy way to access SR fax online services to send,
+  receive or query faxes
+test_files: []
+has_rdoc: