phaxio 0.3.1 → 0.4.0

data/README.md

@@ -2,7 +2,7 @@
 
 A Ruby gem for interacting with the [Phaxio API]( https://www.phaxio.com/docs ).
 
-
+**Note: This gem only runs on Ruby version 1.9.+**
 
 ## Installation
 
@@ -35,8 +35,15 @@ To send a fax:
 
 * send_fax - `Phaxio.send_fax(to: "0123456789", filename: "test.pdf")`
 * test_receive - `Phaxio.test_receive(filename: "test_file.pdf")`
-* get_fax_status - `Phaxio.get_fax_status(id: "123456")`
-* cancel_fax - `Phaxio.cancel_fax(id: "123456")`
+* provision_number - `Phaxio.provision_number(area_code: 802)`
+* release_number - `Phaxio.release_number(number: "8021112222")`
+* list_numbers - `Phaxio.list_numbers(area_code: 802)`
+* get_fax_file - `Phaxio.get_fax_file(id: 123456, type: p)` 
+* list_faxes - `Phaxio.list_numbers(area_code: 802)`
+* list_faxes - `Phaxio.list_faxes(start: Time.now - 48000,
+end: Time.now)`
+* get_fax_status - `Phaxio.get_fax_status(id: 123456)`
+* cancel_fax - `Phaxio.cancel_fax(id: 123456)`
 * get_account_status - `Phaxio.get_account_status`
 
 ### Example
@@ -51,6 +58,12 @@ To send a fax:
     @fax = Phaxio.send_fax(to: '15555555555', string_data: "hello world")
     Phaxio.get_fax_status(id: @fax["faxId"])
 
+    # Get a Fax and save it as a PDF
+    @pdf = Phaxio.get_fax_file(id: @fax["faxId"], type: "p")
+    File.open("received_test.pdf", "w") do |file|
+      file << @pdf
+    end
+
 ## Contributing
 
 1. Fork it

data/lib/phaxio/client.rb

@@ -65,7 +65,6 @@ module Phaxio
     # Returns a HTTParty::Response object containing a success bool,
     # a String message, and an in faxID.
     def send_fax(options)
-      options.merge!({api_key: api_key, api_secret: api_secret})
       send_post("/send", options)
     end
 
@@ -86,10 +85,109 @@ module Phaxio
     # Returns a HTTParty::Response object containing a success bool
     # and a String message.
     def test_receive(options)
-      options.merge!({api_key: api_key, api_secret: api_secret})
       send_post("/testReceive", options)
     end
 
+    # Public: Provision a phone number that you can use to receive faxes in
+    #         your Phaxio account.
+    #
+    # options - The Hash options used to refine the selection (default: {}):
+    #           area_code    - The integer area code of the number you'd like
+    #                          to provision (required).
+    #           callback_url - A callback URL that Phaxio will post to when a
+    #                          fax is received by this number. This will
+    #                          override the global receive callback URL, if you
+    #                          have one set (optional).
+    #
+    # Examples
+    #
+    #   Phaxio.provision_number(area_code: 802)
+    #
+    # Returns a HTTParty::Response object containing a success bool, a string
+    # message, and data containing the phone number, city, state, cost,
+    # last_billed_at, and the date the number was provisioned at.
+    def provision_number(options)
+      send_post("/provisionNumber", options)
+    end
+
+    # Public: Release a phone number that you no longer need. Once a phone
+    #         number is released you will no longer be charged for it.
+    #
+    # options - The Hash options used to refine the selection (default: {}):
+    #           number - The String of the phone number you want to release
+    #                    (required).
+    #
+    # Examples
+    #
+    #   Phaxio.release_number(number: "8021112222")
+    #
+    # Returns a HTTParty::Response object containing a success bool and a
+    # string message.
+    def release_number(options)
+      send_post("/releaseNumber", options)
+    end
+
+    # Public: Get a detailed list of the phone numbers you current own on
+    #         Phaxio.
+    #
+    # options - The Hash options used to refne th selection (default: {}):
+    #           area_code - An integer area code you'd like to filter by 
+    #                       (optional).
+    #           number    - A String phone number you'd like to retrieve
+    #                       (optional).
+    #
+    # Examples
+    #
+    #   Phaxio.list_numbers # list all the numbers you own
+    #
+    #   Phaxio.list_numbers(area_code: 802) # list all numbers in the 802 area
+    #
+    #   Phaxio.list_numbers(number: "8021112222") # show specific number detail
+    #
+    # Returns a HTTParty::Reponse object containing a success bool, a message,
+    # and the data attributes containing the queried phone number(s) details.
+    def list_numbers(options = {})
+      send_post("/numberList", options)
+    end
+
+    # Public: Get an image thumbnail or PDF file for a fax. For images to work
+    #         file storage must not be disabled with Phaxio.
+    #
+    # options - The Hash options used to refine the selection (default: {}):
+    #           id   - The integer fax id of the fax you wish to retreive
+    #                  (required).
+    #           type - An enum for the type return, defaults to 'p' (optional):
+    #                  s - Small JPG format thumbnail of the fax, 129 x 167 px.
+    #                  l - Large JPG format thumbnail of the fax, 300 x 388 px.
+    #                  p - PDF version of the fax (default).
+    #
+    # Examples
+    #
+    #   Phaxio.get_fax_file(id: 1234, type: p)
+    #   Phaxio.get_fax_file(id: 3254, type: l)
+    #
+    # Returns the fax as the type specified in the call, defaults to PDF.
+    def get_fax_file(options)
+      send_post("/faxFile", options)
+    end
+
+    # Public: List faxes within the specified time range.
+    #
+    # options - The Hash options used to refine the selection (default: {}):
+    #           start - The Unix Timestamp for the beginning of the range
+    #                   (required).
+    #           end   - The Unix Timestamp for the end of the range (required).
+    #
+    # Examples
+    #
+    #   Phaxio.list_faxes(start: 1293861600, end: 1294034400)
+    #
+    # Returns a HTTParty::Response object containing a success bool, a string
+    # message, paging information, and the fax data.
+    def list_faxes(options)
+      send_post("/faxList", options)
+    end
+
     # Public: Get the status of a specific fax.
     #
     # options - The Hash options used to refine the selection (default: {}):
@@ -107,7 +205,6 @@ module Phaxio
         raise StandardError, "You must include a fax id."
       end
 
-      options.merge!({api_key: api_key, api_secret: api_secret})
       send_post("/faxStatus", options)
     end
 
@@ -123,7 +220,6 @@ module Phaxio
     # Returns a HTTParty::Response object containing a success bool
     # and a String message.
     def cancel_fax(options)
-      options.merge!({api_key: api_key, api_secret: api_secret})
       send_post("/faxCancel", options)
     end
 

data/lib/phaxio/version.rb

@@ -1,3 +1,3 @@
 module Phaxio
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

data/test/support/responses/list_faxes.json

@@ -0,0 +1,68 @@
+{
+    "success":true,
+    "message":"Retrieved faxes successfully",
+    "paging":{
+        "max_per_page":1000,
+        "page":1,
+        "total_pages":1,
+        "total_results":3
+    },
+    "data":[
+{
+            "id":123456,
+            "num_pages":3,
+            "cost":21,
+            "direction":"sent",
+            "status":"success",
+            "is_test":true,
+            "requested_at":1293910680,
+            "completed_at":1293911100,
+            "recipients":[
+{
+                    "number":"4141234567",
+                    "status":"success",
+                    "completed_at":1293911100
+                }
+            ]
+        },
+{
+            "id":123457,
+            "num_pages":1,
+            "cost":7,
+            "direction":"sent",
+            "status":"success",
+            "is_test":false,
+            "requested_at":1293984720,
+            "completed_at":1293985800,
+            "recipients":[
+{
+                    "number":"4145554567",
+                    "status":"success",
+                    "completed_at":1293985800
+                }
+            ]
+        },
+{
+            "id":123458,
+            "num_pages":1,
+            "cost":14,
+            "direction":"sent",
+            "status":"success",
+            "is_test":false,
+            "requested_at":1294094700,
+            "completed_at":1294095000,
+            "recipients":[
+{
+                    "number":"4145554568",
+                    "status":"success",
+                    "completed_at":1294095000
+                },
+{
+                    "number":"4145554567",
+                    "status":"success",
+                    "completed_at":1293985800
+                }
+            ]
+        }
+    ]
+}

data/test/support/responses/list_numbers.json

@@ -0,0 +1,22 @@
+{
+    "success":true,
+    "message":"Retrieved user phone numbers successfully",
+    "data":[
+{
+            "number":"8021112222",
+            "city":"Burlington",
+            "state":"Vermont",
+            "cost":200,
+            "last_billed_at":"2012-10-11 10:51:33",
+            "provisioned_at":"2012-10-11 10:51:33"
+        },
+{
+            "number":"8023334444",
+            "city":"Montpelier",
+            "state":"Vermont",
+            "cost":200,
+            "last_billed_at":"2012-10-11 10:51:33",
+            "provisioned_at":"2012-10-11 10:51:33"
+        }
+    ]
+}

data/test/support/responses/provision_number.json

@@ -0,0 +1,12 @@
+{
+    "success":true,
+    "message":"Number provisioned successfully!",
+    "data":{
+        "number":"8021112222",
+        "city":"Burlington",
+        "state":"Vermont",
+        "cost":200,
+        "last_billed_at":"2012-10-11 10:00:44",
+        "provisioned_at":"2012-10-11 10:00:44"
+    }
+}

data/test/support/responses/release_number.json

@@ -0,0 +1,7 @@
+{
+    "success":true,
+    "message":"Number released successfully!",
+    "data":[
+
+    ]
+}

data/test/test_helper.rb

@@ -3,6 +3,11 @@ require "test/unit"
 require "fakeweb"
 require "lib/phaxio"
 
+Phaxio.config do |config|
+  config.api_key = "12345678910"
+  config.api_secret = "10987654321"
+end
+
 FakeWeb.register_uri(:post, "https://api.phaxio.com/v1/send",
   :body         => File.open("test/support/responses/send_success.json").read,
   :content_type => "application/json")
@@ -15,6 +20,26 @@ FakeWeb.register_uri(:post, "https://api.phaxio.com/v1/testReceive",
   :body         => File.open("test/support/responses/test_receive.json").read,
   :content_type => "application/json")
 
+FakeWeb.register_uri(:post, "https://api.phaxio.com/v1/provisionNumber",
+  :body         => File.open("test/support/responses/provision_number.json").read,
+  :content_type => "application/json")
+
+FakeWeb.register_uri(:post, "https://api.phaxio.com/v1/releaseNumber",
+  :body         => File.open("test/support/responses/release_number.json").read,
+  :content_type => "application/json")
+
+FakeWeb.register_uri(:post, "https://api.phaxio.com/v1/numberList",
+  :body         => File.open("test/support/responses/list_numbers.json").read,
+  :content_type => "application/json")
+
+FakeWeb.register_uri(:post, "https://api.phaxio.com/v1/faxFile",
+  :body         => File.open("test/support/responses/test.pdf").read,
+  :content_type => "application/pdf")
+
+FakeWeb.register_uri(:post, "https://api.phaxio.com/v1/faxList",
+  :body         => File.open("test/support/responses/list_faxes.json").read,
+  :content_type => "application/json")
+
 FakeWeb.register_uri(:post, "https://api.phaxio.com/v1/faxStatus",
   :body         => File.open("test/support/responses/fax_status_success.json").read,
   :content_type => "application/json")

data/test/test_phaxio.rb

@@ -1,13 +1,6 @@
 require_relative "test_helper"
 
 class TestPhaxio < Test::Unit::TestCase
-  def setup
-    Phaxio.config do |config|
-      config.api_key = "12345678910"
-      config.api_secret = "10987654321"
-    end
-  end
-
   def test_config
     assert_equal "12345678910", Phaxio.api_key
     assert_equal "10987654321", Phaxio.api_secret
@@ -29,14 +22,43 @@ class TestPhaxio < Test::Unit::TestCase
     assert_equal "Test fax received from 234567890. Calling back now...", @response["message"]
   end
 
+  def test_provision_number
+    @response = Phaxio.provision_number(area_code: 802)
+    assert_equal true, @response["success"]
+    assert_equal "Number provisioned successfully!", @response["message"]
+    assert_equal "Vermont", @response["data"]["state"]
+  end
+
+  def test_release_number
+    @response = Phaxio.release_number(number: "8021112222")
+    assert_equal true, @response["success"]
+    assert_equal "Number released successfully!", @response["message"]
+  end
+
+  def test_list_numbers
+    @response = Phaxio.list_numbers(area_code: 802)
+    assert_equal true, @response["success"]
+    assert_equal "Retrieved user phone numbers successfully", @response["message"]
+  end
+
+  def test_get_fax_file
+    @response_pdf = Phaxio.get_fax_file(id: 1234, type: p)
+    assert_equal 6725, @response_pdf.size
+  end
+
+  def test_list_faxes
+    @response = Phaxio.list_faxes(start: 1293861600, end: 1294034400)
+    assert_equal true, @response["success"]
+  end
+
   def test_get_fax_status
-    @response = Phaxio.get_fax_status(id: "123456")
+    @response = Phaxio.get_fax_status(id: 123456)
     assert_equal true, @response["success"]
     assert_equal "Retrieved fax successfully", @response["message"]
   end
 
   def test_cancel_fax
-    @response = Phaxio.cancel_fax(id: "123456")
+    @response = Phaxio.cancel_fax(id: 123456)
     assert_equal true, @response["success"]
     assert_equal "Fax canceled successfully.", @response["message"]
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phaxio
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-04 00:00:00.000000000 Z
+date: 2012-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httmultiparty
@@ -79,12 +79,16 @@ files:
 - lib/phaxio/client.rb
 - lib/phaxio/version.rb
 - phaxio.gemspec
-- test/support/account_status.json
 - test/support/responses/account_status.json
 - test/support/responses/cancel_success.json
 - test/support/responses/fax_status_success.json
+- test/support/responses/list_faxes.json
+- test/support/responses/list_numbers.json
+- test/support/responses/provision_number.json
+- test/support/responses/release_number.json
 - test/support/responses/send_failure.json
 - test/support/responses/send_success.json
+- test/support/responses/test.pdf
 - test/support/responses/test_receive.json
 - test/test_helper.rb
 - test/test_phaxio.rb
@@ -108,17 +112,21 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.23
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: A Ruby Gem for interacting with Phaxio's JSON API
 test_files:
-- test/support/account_status.json
 - test/support/responses/account_status.json
 - test/support/responses/cancel_success.json
 - test/support/responses/fax_status_success.json
+- test/support/responses/list_faxes.json
+- test/support/responses/list_numbers.json
+- test/support/responses/provision_number.json
+- test/support/responses/release_number.json
 - test/support/responses/send_failure.json
 - test/support/responses/send_success.json
+- test/support/responses/test.pdf
 - test/support/responses/test_receive.json
 - test/test_helper.rb
 - test/test_phaxio.rb

data/test/support/account_status.json

@@ -1,9 +0,0 @@
-{
-    "success":true,
-    "message":"Account status retrieved successfully",
-    "data":{
-        "faxes_sent_this_month":120,
-        "faxes_sent_today":10,
-        "balance":3000
-    }
-}