README.md in phaxio-0.5.0 vs README.md in phaxio-2.0.0
- old
+ new
@@ -1,105 +1,292 @@
-# Phaxio
+# 📠Phaxio
[](https://travis-ci.org/phaxio/phaxio-ruby)
-A Ruby gem for interacting with the [Phaxio API]( https://www.phaxio.com/docs ).
+A Ruby gem for interacting with the [Phaxio API](https://www.phaxio.com/docs/api/v2).
-**Note: This gem only runs on Ruby version 1.9.+**
-
## Installation
-Add this line to your application's Gemfile:
+Add to your application's Gemfile:
- gem 'phaxio'
+``` ruby
+gem 'phaxio', '~> 2.0.0'
+```
And then execute:
- $ bundle
+``` sh
+$ bundle install
+```
Or install it yourself as:
- $ gem install phaxio
+``` sh
+$ gem install phaxio
+```
## Usage
-Configure Phaxio with your api_key and api_secret:
+Set up your API Key, API Secret, and, optionally, Callback Token.
- Phaxio.config do |config|
- config.api_key = "10987654321"
- config.api_secret = "12345678910"
- end
+``` ruby
+require 'phaxio'
-To send a fax:
+Phaxio.api_key = '11111'
+Phaxio.api_secret = '22222'
+Phaxio.callback_token = '33333'
+```
- Phaxio.send_fax(to: "0123456789", filename: File.new("test.pdf"))
+Try sending a fax:
+``` ruby
+fax_file = File.open 'test.pdf', 'rb'
+Phaxio::Fax.create to: '+15558675309', file: fax_file
+```
+
+You can include `Phaxio::Resources` to pull in the resource classes for convenience:
+
+``` ruby
+include Phaxio::Resources
+
+fax_file = File.open 'test.pdf', 'rb'
+Fax.create to: '+15558675309', file: fax_file
+```
+
+
### Currently Supported API Calls
-* send_fax - `Phaxio.send_fax(to: "0123456789", filename: File.new("test.pdf"))`
-* resend_fax - `Phaxio.resend_fax(id: 1234)`
-* test_receive - `Phaxio.test_receive(filename: "test_file.pdf")`
-* 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)`
-* delete_fax - `Phaxio.delete_fax(id: 1234, files_only: true)`
-* get_account_status - `Phaxio.get_account_status`
-* attach_phaxcode_to_pdf - `Phaxio.attach_phaxcode_to_pdf(x: 10, y:10, File.new("input.pdf"))`
-* create_phaxcode - `Phaxio.create_phaxcode(metadata: "some metadata")`
-* supported_countries
-* area_codes
+#### Faxes
-### Example
+##### `Fax.create`
- require 'phaxio'
+Create and send a fax.
- Phaxio.config do |config|
- config.api_key = "your_key"
- config.api_secret = "your_secret"
- end
+``` ruby
+fax_file = File.open 'test.pdf', 'rb'
+ref = Fax.create to: '+15558675309', file: fax_file
+# => Fax::Reference(id: 1234)
+fax = ref.get
+# => Fax(id: 1234, num_pages: 1, ...)
+```
- @fax = Phaxio.send_fax(to: '15555555555', string_data: "hello world")
- Phaxio.get_fax_status(id: @fax["faxId"])
+##### `Fax.list`
- # 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
+List faxes in date range.
+``` ruby
+start = 2.weeks.ago
+stop = 1.week.ago
+faxes = Fax.list created_after: start, created_before: stop
+# => Phaxio::Resource::Collection([Fax(id: 1234, ...), ...])
+faxes.length
+# => 5
+faxes.map(&:cost).inject(&:+)
+# => 35
+```
+
+##### `Fax.get`
+
+Get information about a specific fax.
+
+``` ruby
+fax = Fax.get 1234
+# => Fax(id: 1234, ...)
+```
+
+##### `Fax.cancel`
+
+Cancel a fax.
+
+``` ruby
+Fax.cancel 1234
+# => Fax::Reference(id: 1234)
+```
+
+##### `Fax.resend`
+
+Resend a fax.
+
+``` ruby
+Fax.resend 1234
+# => Fax::Reference(id: 5678)
+```
+
+##### `Fax.delete`
+
+Delete a fax. Only test faxes are allowed to be deleted.
+
+``` ruby
+Fax.delete 1234
+# => true
+```
+
+##### `Fax.delete_file`
+
+Delete fax file.
+
+``` ruby
+Fax.delete_file 1234
+# => true
+```
+
+##### `Fax.file`
+
+``` ruby
+Fax.file 1234
+# => File
+```
+
+##### `Fax.test_receive`
+
+Test receiving a fax.
+
+``` ruby
+fax_file = File.open 'test.pdf', 'rb'
+Fax.test_receive file: fax_file
+# => true
+```
+
+#### Countries
+
+##### `Public::Country.list`
+
+Get a list of supported countries.
+
+``` ruby
+Public::Country.list
+# => Phaxio::Resource::Collection([Public::Country(alpha2: 'US', ...), ...])
+```
+
+#### Phone Numbers
+
+##### `PhoneNumber.create`
+
+Provision a new phone number.
+
+``` ruby
+PhoneNumber.create country_code: 1, area_code: 555
+# => PhoneNumber(phone_number: '+15558675309', ...)
+```
+
+##### `PhoneNumber.list`
+
+List phone numbers that you own on Phaxio.
+
+``` ruby
+PhoneNumber.list
+# => Phaxio::Resource::Collection([PhoneNumber(phone_number: '+15558675309', ...), ...])
+```
+
+##### `PhoneNumber.get`
+
+Get information about a specific phone number.
+
+``` ruby
+PhoneNumber.get '+15558675309'
+# => PhoneNumber(phone_number: '+15558675309', ...)
+```
+
+##### `PhoneNumber.delete`
+
+Release a phone number.
+
+``` ruby
+PhoneNumber.delete '+15558675309'
+# => true
+```
+
+#### Area Codes
+
+##### `Public::AreaCode.list`
+
+Lists available area codes for purchasing Phaxio numbers.
+
+``` ruby
+area_codes = Public::AreaCode.list toll_free: true
+# => Phaxio::Resource::Collection([Public::AreaCode(city: 'Toll Free Service', ...), ...], page: 1)
+```
+
+#### PhaxCodes
+
+##### `PhaxCode.create`
+
+Creates a PhaxCode. Returns data about the PhaxCode by default, or a .png file if `type: 'png'` is
+passed.
+
+``` ruby
+PhaxCode.create metadata: 'test_phax_code'
+# => PhaxCode(identifier: 'phax-code-identifier')
+PhaxCode.create type: 'png'
+# => File
+```
+
+##### `PhaxCode.get`
+
+Gets a PhaxCode. Returns data about the PhaxCode by default, or a .png file if `type: 'png'` is
+passed.
+
+``` ruby
+PhaxCode.get 'phax-code-identifier'
+# => PhaxCode(identifier: 'phax-code-identifier', metadata: 'phax-code-metadata')
+PhaxCode.get 'phax-code-identifier', type: 'png'
+# => File
+```
+
+#### Account
+
+##### `Account.get`
+
+Get information about your Phaxio account.
+
+``` ruby
+Account.get
+# => Account(balance: 1000, faxes_today: 0, faxes_this_month: 100)
+```
+
+#### Callback
+
+##### `Callback.valid_signature?`
+
+Validate the callback signature sent with a Phaxio callback. Requires that Phaxio.callback_token be
+set.
+
+``` ruby
+Callback.valid_signature? received_signature, callback_url, received_params, received_files
+# => true
+```
+
## Callback Validation Example with Sinatra
- require 'sinatra/base'
- require 'phaxio'
+``` ruby
+require 'sinatra/base'
+require 'phaxio'
- class PhaxioCallbackExample < Sinatra::Base
- Phaxio.config do |config|
- config.api_key = '0123456789'
- config.api_secret = '0123456789'
- config.callback_token = '0123456789'
- end
+class PhaxioCallbackExample < Sinatra::Base
+ Phaxio.config do |config|
+ config.api_key = '0123456789'
+ config.api_secret = '0123456789'
+ config.callback_token = '0123456789'
+ end
- post '/phaxio_callback' do
- if Phaxio.valid_callback_signature?(
- request.env['HTTP_X_PHAXIO_SIGNATURE'],
- request.url, callback_params, params[:filename])
- 'Success'
- else
- 'Invalid callback signature'
- end
- end
+ post '/phaxio_callback' do
+ signature = request.env['HTTP_X_PHAXIO_SIGNATURE']
+ url = request.url
+ file_params = params[:filename]
+ if Phaxio::Callback.valid_signature? signature, url, callback_params, file_params
+ 'Success'
+ else
+ 'Invalid callback signature'
+ end
+ end
- def callback_params
- params.select do |key, _value|
- %w(success is_test direction fax metadata).include?(key)
- end
- end
+ def callback_params
+ params.select do |key, _value|
+ %w(success is_test direction fax metadata message).include?(key)
end
+ end
+end
+```
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)