phaxio 0.4.0 → 2.1.0.pre

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7f20cd3d8695312c8b64cf40cc01b8fe0e320b921a3527abc1ca005a9d140b11
+  data.tar.gz: '088662055ff2bd6ebbeb5055ad7316bd6d99acf9a93249383d9ad1aa08133a4b'
+SHA512:
+  metadata.gz: 99cfc91fefd07016507eb20049f5c7afeca903d2c227941bcd55a1cd14913faa1b03e69a2ceea1798da457bf338a48e5ad7c212f107aba598378965210a0d24a
+  data.tar.gz: cf3b858ff97a2b005f50a21709ee524fd20b6fc12080a59a48d57842b9e295f18de91a20f48ba5f9f1b64d632e5a38d7d375b0af8e323cea2232df49421deb93

data/.gitignore

@@ -16,3 +16,5 @@ test/tmp
 test/version_tmp
 tmp
 .DS_Store
+.envrc
+.env

data/.travis.yml

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

data/Gemfile

@@ -1,8 +1,14 @@
 source 'https://rubygems.org'
 
-gem "fakeweb", "~> 1.3.0"
-gem "httmultiparty", "~> 0.3.8"
-gem "rake", "~> 0.9.2.2"
-
-# Specify your gem's dependencies in phaxio.gemspec
 gemspec
+
+group :development do
+  gem 'bundler'
+  gem 'rake'
+  gem 'rspec', '~> 3.7'
+  gem 'vcr'
+  gem 'webmock'
+  gem 'pry'
+  gem 'yard'
+  gem 'dotenv', require: false
+end

data/README.md

@@ -1,68 +1,324 @@
-# Phaxio
+# 📠 Phaxio
 
-A Ruby gem for interacting with the [Phaxio API]( https://www.phaxio.com/docs ).
+[![Build Status](https://travis-ci.org/phaxio/phaxio-ruby.svg?branch=master)](https://travis-ci.org/phaxio/phaxio-ruby)
 
-**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
+```
+
+You can include `Phaxio::Resources` to pull in the resource classes for convenience:
 
-To send a fax:
+``` ruby
+include Phaxio::Resources
+
+fax_file = File.open 'test.pdf', 'rb'
+Fax.create to: '+15558675309', file: fax_file
+```
 
-    Phaxio.send_fax(to: "0123456789", filename: "test.pdf")
 
 ### Currently Supported API Calls
 
-* send_fax - `Phaxio.send_fax(to: "0123456789", filename: "test.pdf")`
-* 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)`
-* get_account_status - `Phaxio.get_account_status`
-
-### Example
-
-    require 'phaxio'
-
-    Phaxio.config do |config|
-      config.api_key = "your_key"
-      config.api_secret = "your_secret"
+#### Faxes
+
+##### `Fax.create`
+
+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
+
+``` ruby
+require 'sinatra/base'
+require 'phaxio'
+
+class PhaxioWebhookExample < Sinatra::Base
+  Phaxio.callback_token = 'YOUR WEBHOOK TOKEN HERE'
+  
+  post '/webhook' do
+    signature = request.env['HTTP_X_PHAXIO_SIGNATURE']
+    url = request.url
+    file_params = params[:file]
+    if Phaxio::Callback.valid_signature? signature, url, webhook_params, file_params
+      'Success'
+    else
+      'Invalid webhook signature'
+    end
+  end
+
+  def webhook_params
+    params.select do |key, _value|
+      %w(success is_test direction fax metadata message event_type).include?(key)
+    end
+  end
+end
+```
+
+## Webhook Validation Example with Rails Controller
+
+``` ruby
+class WebhookController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+	def index
+    signature = request.headers['X-Phaxio-Signature']  
+    Phaxio.callback_token = 'YOUR WEBHOOK TOKEN HERE'
+    url = request.original_url
+
+    Rails.logger.debug "URL: " + url
+    Rails.logger.debug "Signature: " + signature
+    Rails.logger.debug "params: " + params.inspect
+    Rails.logger.debug "webhook_params: " + webhook_params.to_h.inspect
+    
+    if Phaxio::Callback.valid_signature? signature, url, webhook_params.to_h, file_params
+      Rails.logger.debug "Success"
+      render plain: 'Success'
+    else
+      Rails.logger.debug "Invalid callback signature"
+      render plain: 'Invalid callback signature'
     end
+  end
 
-    @fax = Phaxio.send_fax(to: '15555555555', string_data: "hello world")
-    Phaxio.get_fax_status(id: @fax["faxId"])
+  def webhook_params 
+    params.permit(:success, :is_test, :direction, :fax, :metadata, :event_type, :message)
+  end
 
-    # 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
+  def file_params 
+    if params[:file]
+      [{ :name => 'file', :tempfile => params[:file].tempfile }]
     end
+  end
+end
+```
 
 ## Contributing
 

data/Rakefile

@@ -1,13 +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 tests'
+task :default => :spec

data/lib/phaxio.rb

@@ -1,4 +1,49 @@
-require "httmultiparty"
+require 'base64'
+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 ata].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