phaxio 0.5.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b0ba3d3a1d93ed66b41b2f43e4830301b1cf636f
-  data.tar.gz: 61dec61548a074dbaedd1e450fe8aa23bc729740
+  metadata.gz: 6a10449404bdb1df029a52a878f49202589e727d
+  data.tar.gz: f500188f94760b8300dc2f63b17eb4ad31edc5fa
 SHA512:
-  metadata.gz: c04abdcfb62078eace54eb05a7560cd183aa4b70717f0c267833b5808f39130a89f6c448713b6f9036b038894909b8ae9cc97234208f713a2bcb665723f5b2f9
-  data.tar.gz: 48ea7099e4556e635f0a66dcfd61d5f205594835230a7797effd4e823b7762d24affe7fed8dd3fb2c759fd85f9a015353b63532aaf17f2adaa1b6df1476e9643
+  metadata.gz: df06285d6e87fbc048f0ebcad0cd5ee608ccfb0b45c6813926f272c4302aa5dc60421445df11bacc6fae2e26a32951912ca201376a56c77bcd2e5fa71e0e5976
+  data.tar.gz: 9d5bcfa978e6e92317d17d4bb0a31e4cd2f33f57d96f8241721bc581be34c768623704d951d4a177f5634dc0eb6a7f2cff4c8db7588e6e286a61ba2aa5020dd3

data/.gitignore

@@ -17,4 +17,4 @@ test/version_tmp
 tmp
 .DS_Store
 .envrc
-.idea
+.env

data/.travis.yml

@@ -1,10 +1,11 @@
 language: ruby
 
 rvm:
-  - 1.9.3
   - 2.0.0
   - 2.1
   - 2.2
+  - 2.3
+  - 2.4
   - jruby-19mode
 
 sudo: false

data/Gemfile

@@ -1,3 +1,13 @@
 source 'https://rubygems.org'
 
 gemspec
+
+group :development do
+  gem 'bundler'
+  gem 'rake', '~> 10'
+  gem 'rspec', '~> 3.7'
+  gem 'vcr'
+  gem 'webmock'
+  gem 'pry'
+  gem 'yard'
+end

data/README.md

@@ -1,104 +1,291 @@
-# Phaxio
+# 📠 Phaxio
 
 [![Build Status](https://travis-ci.org/phaxio/phaxio-ruby.svg?branch=master)](https://travis-ci.org/phaxio/phaxio-ruby)
 
-A Ruby gem for interacting with the [Phaxio API]( https://www.phaxio.com/docs ).
-
-**Note: This gem only runs on Ruby version 1.9.+**
+A Ruby gem for interacting with the [Phaxio API](https://www.phaxio.com/docs/api/v2).
 
 ## 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'
+
+Phaxio.api_key = '11111'
+Phaxio.api_secret = '22222'
+Phaxio.callback_token = '33333'
+```
+
+Try sending a fax:
+
+``` ruby
+fax_file = File.open 'test.pdf', 'rb'
+Phaxio::Fax.create to: '+15558675309', file: fax_file
+```
 
-To send a fax:
+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
+```
 
-    Phaxio.send_fax(to: "0123456789", filename: File.new("test.pdf"))
 
 ### 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
-
-### Example
-
-    require 'phaxio'
-
-    Phaxio.config do |config|
-      config.api_key = "your_key"
-      config.api_secret = "your_secret"
-    end
+#### Faxes
 
-    @fax = Phaxio.send_fax(to: '15555555555', string_data: "hello world")
-    Phaxio.get_fax_status(id: @fax["faxId"])
+##### `Fax.create`
 
-    # 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
+Create and send a fax.
+
+``` 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.list`
+
+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'
-
-    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
-
-      def callback_params
-        params.select do |key, _value|
-          %w(success is_test direction fax metadata).include?(key)
-        end
-      end
+``` 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
+
+  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 message).include?(key)
     end
+  end
+end
+```
 
 ## Contributing
 

data/Rakefile

@@ -1,21 +1,11 @@
 #!/usr/bin/env rake
-require "bundler/gem_tasks"
+require 'rake'
+require 'rspec/core/rake_task'
 
-require 'rake/testtask'
-
-Rake::TestTask.new do |t|
-  t.libs << 'test'
-  t.test_files = FileList['test/test*.rb']
-  t.verbose = true
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = Dir.glob('spec/**/*_spec.rb')
+  t.rspec_opts = '--format documentation'
 end
 
 desc 'Run tests'
-task :default => :test
-
-desc 'Run integration tests'
-task :integration_tests do
-  integration_tests_path = File.expand_path(
-    '../test/integration/*_integration_test.rb', __FILE__
-  )
-  FileList[integration_tests_path].each { |file| require file }
-end
+task :default => :spec

data/lib/phaxio.rb

@@ -1,4 +1,48 @@
-require "httmultiparty"
+require 'json'
+require 'tempfile'
+require 'openssl'
+require 'time'
+require 'faraday'
+require 'active_support/core_ext/hash/indifferent_access'
+require 'mime/types/full'
+require 'phaxio/version'
+require 'phaxio/config'
+require 'phaxio/client'
+require 'phaxio/error'
+require 'phaxio/resource'
+require 'phaxio/resources'
 
-require "phaxio/version"
-require "phaxio/client"
+Dir[File.expand_path(File.join('..', 'phaxio', 'helpers', '*.rb'), __FILE__)].each do |file|
+  require file
+end
+
+%w[fax_recipient fax account callback phax_code phone_number public].each do |filename|
+  require File.expand_path(File.join('..', 'phaxio', 'resources', filename), __FILE__)
+end
+
+module Phaxio
+  include Resources
+
+  class << self
+    # @!attribute api_key
+    #   @see Config.api_key
+    # @!attribute api_secret
+    #   @see Config.api_secret
+    # @!attribute callback_token
+    #   @see Config.callback_token
+    # @!attribute api_endpoint
+    #   @see Config.api_endpoint
+    %w(api_key api_secret callback_token api_endpoint).each do |config_attribute|
+      # Define getters
+      define_method(config_attribute) do
+        Config.public_send config_attribute
+      end
+
+      # Define setters
+      setter = "#{config_attribute}="
+      define_method(setter) do |value|
+        Config.public_send setter, value
+      end
+    end
+  end
+end