interfax 1.0.0.beta.1 → 1.0.0.beta.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6ca2a92fceee202dd5447d835b0dddeafa67c009
-  data.tar.gz: a867d88f73fa55d5d6718f004b5c2b434fa2e746
+  metadata.gz: a1e9c472700ce6e06a0b6e73c8404177ff8798ce
+  data.tar.gz: e4d2321131a15cfdbf3a7a35f25260bbf72877b3
 SHA512:
-  metadata.gz: 0252390bb07c553572fcefd0138789eac6bc515fcf975983ad1cf96d0ad97522a19c7b4a43b0cac1172f816d3d48a90638781a013d8fd0cef615b1bc89f7ff9c
-  data.tar.gz: c6a052dbed6f1b6832349b01858061d9946138e8ccdfb72cbcd13f4e6a9c487583f31fc385abbfc86c5d06a361e25aa4c321b7f144fc3a5b28fef331d5e6a8e0
+  metadata.gz: c8e357151a090187121cadfec40d95604b1b5e45f2b8ea44347be9a26935526a203ccb2623c7af26441f23c07cb76da5927baa19dc31e5d2555528effff54cc1
+  data.tar.gz: c92ba400dc2def9cca50d94eb27f3d8471e9d2d3b79eed7aae34f7299e7f4c6ef7787208da649f4acd5c5811dffbfa1ba3a8adbec0f8efb54d6f19222a36698c

data/README.md

@@ -8,7 +8,7 @@ Send and receive faxes in Ruby with the [InterFAX](https://www.interfax.net/en/d
 
 ## Installation
 
-Either install directly or via bundler.
+This gem requires 2.1+. You can install install it directly or via bundler.
 
 ```ruby
 gem 'interfax', '~> 1.0.0'
@@ -22,27 +22,31 @@ To send a fax from a PDF file:
 require 'interfax'
 
 interfax = InterFAX::Client.new(username: 'username', password: 'password')
-interfax.deliver(faxNumber: "+11111111112", file: 'folder/fax.pdf')
+fax = interfax.deliver(faxNumber: "+11111111112", file: 'folder/fax.pdf')
+fax = fax.reload # resync with API to get latest status
+fax.status # Success if 0. Pending if < 0. Error if > 0
 ```
 
 # Usage
 
-[Client](#client) | [Account](#account) | [Outbound](#outbound) | [Inbound](#inbound) | [Helper Classes](#helper-classes)
+[Client](#client) | [Account](#account) | [Outbound](#outbound) | [Inbound](#inbound) | [Documents](#documents) | [Helper Classes](#helper-classes)
 
 ## Client
 
 The client follows the [12-factor](12factor.net/config) apps principle and can be either set directly or via environment variables.
 
 ```ruby
-# using parameters
+# Initialize using parameters
 interfax = InterFAX::Client.new(username: '...', password: '...')
 
-# using environment variables:
+# Alternatice: Initialize using environment variables
 # * INTERFAX_USERNAME
 # * INTERFAX_PASSWORD
 interfax = InterFAX::Client.new
 ```
 
+All connections are established over HTTPS.
+
 ## Account
 
 ### Balance
@@ -54,7 +58,7 @@ interfax.account.balance
 => 9.86
 ```
 
-**Documentation:** [`GET /accounts/self/ppcards/balance`](https://www.interfax.net/en/dev/rest/reference/3001)
+**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/3001)
 
 ## Outbound
 
@@ -69,16 +73,22 @@ Submit a fax to a single destination number.
 There are a few ways to send a fax. One way is to directly provide a file path or url.
 
 ```ruby
-interfax.outbound.deliver(faxNumber: "+11111111112", file: 'file://fax.pdf')
+# with a path
+interfax.outbound.deliver(faxNumber: "+11111111112", file: 'folder/fax.txt')
+# with a URL
 interfax.outbound.deliver(faxNumber: "+11111111112", file: 'https://s3.aws.com/example/fax.pdf')
 ```
 
+InterFAX supports over 20 file types including HTML, PDF, TXT, Word, and many more. For a full list see the [Supported File Types](https://www.interfax.net/en/help/supported_file_types) documentation.
+
 The returned object is a `InterFAX::Outbound::Fax` with just an `id`. You can use this object to load more information, get the image, or cancel the sending of the fax.
 
 ```rb
 fax = interfax.outbound.deliver(faxNumber: "+11111111112", file: 'file://fax.pdf')
-fax = fax.reload # load more information about this fax
-fax.image     # load the image sent to the faxNumber
+fax = fax.reload # Reload fax, allowing you to inspect the status and more
+
+fax.id        # the ID of the fax that can be used in some of the other API calls
+fax.image     # returns an image representing the fax sent to the faxNumber
 fax.cancel    # cancel the sending of the fax
 ```
 
@@ -86,7 +96,7 @@ Alternatively you can create an `InterFAX::File` with binary data and pass this
 
 ```ruby
 data = File.open('file://fax.pdf').read
-file = InterFAX::File.new(data, mime_type: 'application/pdf')
+file = interfax.files.create(data, mime_type: 'application/pdf')
 interfax.outbound.deliver(faxNumber: "+11111111112", file: file)
 ```
 
@@ -98,9 +108,7 @@ interfax.outbound.deliver(faxNumber: "+11111111112", files: ['file://fax.pdf', '
 
 Under the hood every path and string is turned into a  [InterFAX::File](#InterFax::File) object. For more information see [the documentation](#InterFax::File) for this class.
 
-**Documentation:** [`POST /outbound/faxes`](https://www.interfax.net/en/dev/rest/reference/2918)
-
-[**Additional options:**](https://www.interfax.net/en/dev/rest/reference/2918) `contact`, `postponeTime`, `retriesToPerform`, `csid`, `pageHeader`, `reference`, `pageSize`, `fitToPage`, `pageOrientation`, `resolution`, `rendering`
+**Options:** [`contact`, `postponeTime`, `retriesToPerform`, `csid`, `pageHeader`, `reference`, `pageSize`, `fitToPage`, `pageOrientation`, `resolution`, `rendering`](https://www.interfax.net/en/dev/rest/reference/2918)
 
 **Alias**: `interfax.deliver`
 
@@ -115,11 +123,11 @@ Get a list of recent outbound faxes (which does not include batch faxes).
 ```ruby
 interfax.outbound.all
 => [#<InterFAX::Outbound::Fax>, ...]
+interfax.outbound.all(limit: 1)
+=> [#<InterFAX::Outbound::Fax>]
 ```
 
-**Documentation:** [`GET /outbound/faxes`](https://www.interfax.net/en/dev/rest/reference/2920)
-
-[**Options:**](https://www.interfax.net/en/dev/rest/reference/2920) `limit`, `lastId`, `sortOrder`, `userId`
+**Options:** [`limit`, `lastId`, `sortOrder`, `userId`](https://www.interfax.net/en/dev/rest/reference/2920)
 
 ----
 
@@ -134,7 +142,7 @@ interfax.outbound.completed(123, 234)
 => [#<InterFAX::Outbound::Fax>, ...]
 ```
 
-**Documentation:** [`GET /outbound/faxes/completed`](https://www.interfax.net/en/dev/rest/reference/2972)
+**More:** [none](https://www.interfax.net/en/dev/rest/reference/2972)
 
 ----
 
@@ -149,7 +157,7 @@ interfax.outbound.find(123456)
 => #<InterFAX::Outbound::Fax>
 ```
 
-**Documentation:** [`GET /outbound/faxes/:id`](https://www.interfax.net/en/dev/rest/reference/2921)
+**More:** [none](https://www.interfax.net/en/dev/rest/reference/2921)
 
 ----
 
@@ -168,7 +176,7 @@ image.save('fax.tiff')
 => # saves image to file
 ```
 
-**Documentation:** [`GET /outbound/faxes/:id/image`](https://www.interfax.net/en/dev/rest/reference/2941)
+**More:** [none](https://www.interfax.net/en/dev/rest/reference/2941)
 
 ----
 
@@ -183,7 +191,7 @@ interfax.outbound.cancel(123456)
 => #<InterFAX::Outbound::Fax>
 ```
 
-**Documentation:** [`GET /outbound/faxes/:id/cancel`](https://www.interfax.net/en/dev/rest/reference/2939)
+**More:** [none](https://www.interfax.net/en/dev/rest/reference/2939)
 
 ----
 
@@ -198,9 +206,7 @@ interfax.outbound.search(faxNumber: '+1230002305555')
 => [#<InterFAX::Outbound::Fax>, ...]
 ```
 
-**Documentation:** [`GET /outbound/search`](https://www.interfax.net/en/dev/rest/reference/2959)
-
-[**Options:**](https://www.interfax.net/en/dev/rest/reference/2959) `ids`, `reference`, `dateFrom`, `dateTo`, `status`, `userId`, `faxNumber`, `limit`, `offset`
+**Options:** [`ids`, `reference`, `dateFrom`, `dateTo`, `status`, `userId`, `faxNumber`, `limit`, `offset`](https://www.interfax.net/en/dev/rest/reference/2959)
 
 ## Inbound
 
@@ -215,11 +221,11 @@ Retrieves a user's list of inbound faxes. (Sort order is always in descending ID
 ```ruby
 interfax.inbound.all
 => [#<InterFAX::Inbound::Fax>, ...]
+interfax.inbound.all(limit: 1)
+=> [#<InterFAX::Inbound::Fax>]
 ```
 
-**Documentation:** [`GET /inbound/faxes`](https://www.interfax.net/en/dev/rest/reference/2935)
-
-[**Options:**](https://www.interfax.net/en/dev/rest/reference/2935) `unreadOnly`, `limit`, `lastId`, `allUsers`
+**Options:** [`unreadOnly`, `limit`, `lastId`, `allUsers`](https://www.interfax.net/en/dev/rest/reference/2935)
 
 ---
 
@@ -234,7 +240,7 @@ interfax.inbound.find(123456)
 => #<InterFAX::Inbound::Fax>
 ```
 
-**Documentation:** [`GET /inbound/faxes/:id`](https://www.interfax.net/en/dev/rest/reference/2938)
+**More:** [none](https://www.interfax.net/en/dev/rest/reference/2938)
 
 ---
 
@@ -253,7 +259,7 @@ image.save('fax.tiff')
 => # saves image to file
 ```
 
-**Documentation:** [`GET /inbound/faxes/:id/image`](https://www.interfax.net/en/dev/rest/reference/2937)
+**More:** [none](https://www.interfax.net/en/dev/rest/reference/2937)
 
 ---
 
@@ -268,7 +274,7 @@ interfax.inbound.email(123456)
 => [#<InterFAX::Email>]
 ```
 
-**Documentation:** [`GET /inbound/faxes/:id/emails`](https://www.interfax.net/en/dev/rest/reference/2930)
+**More:** [none](https://www.interfax.net/en/dev/rest/reference/2930)
 
 ---
 
@@ -285,7 +291,9 @@ interfax.inbound.mark(123456, read: false) # mark unread
 => true
 ```
 
-**Documentation:** [`POST /inbound/faxes/:id/mark`](https://www.interfax.net/en/dev/rest/reference/2936)
+**More:** [none](https://www.interfax.net/en/dev/rest/reference/2936)
+
+---
 
 ### Resend inbound fax
 
@@ -302,6 +310,105 @@ interfax.inbound.resend(123456, email: 'test@example.com')
 => true
 ```
 
+**More:** [none](https://www.interfax.net/en/dev/rest/reference/2929)
+
+---
+
+## Documents
+
+[Create](#create-document) | [Upload chunk](#upload-chunk) | [Get list](#get-document-list) | [Status](#get-document-status) | [Cancel](#cancel-document)
+
+Document allow for uploading of large files up to 20MB in 200kb chunks. The `InterFAX::File` format automatically uses this if needed but a sample implementation would look as followed.
+
+```ruby
+file = File.open('test.pdf', 'rb')
+
+document = interfax.documents.create('test.pdf', file.size)
+
+cursor = 0
+while !file.eof?
+  chunk = file.read(500)
+  next_cursor = cursor + chunk.length
+  document.upload(cursor, next_cursor-1, chunk)
+  cursor = next_cursor
+end
+```
+
+### Create Documents
+
+`interfax.documents.create(name, size, options = {})`
+
+Create a document upload session, allowing you to upload large files in chunks.
+
+```ruby
+interfax.documents.create('large_file.pdf', '231234')
+=> #<InterFAX::Document uri="https://rest.interfax.net/outbound/documents/123456">
+```
+
+**Options:** [`disposition`, `sharing`](https://www.interfax.net/en/dev/rest/reference/2967)
+
+---
+
+### Upload chunk
+
+`interfax.documents.upload(id, range_start, range_end, chunk)`
+
+Upload a chunk to an existing document upload session.
+
+```ruby
+interfax.documents.upload(123456, 0, 999, "....binary-data....")
+=> true
+```
+
+**More:** [none](https://www.interfax.net/en/dev/rest/reference/2966)
+
+---
+
+### Get document list
+
+`interfax.documents.all(options = {})`
+
+Get a list of previous document uploads which are currently available.
+
+```ruby
+interfax.documents.all
+=> #[#<InterFAX::Document>, ...]
+interfax.documents.all(offset: 10)
+=> #[#<InterFAX::Document>, ...]
+```
+
+**Options:** [`limit`, `offset`](https://www.interfax.net/en/dev/rest/reference/2968)
+
+---
+
+### Get document status
+
+`interfax.documents.find(id)`
+
+Get the current status of a specific document upload.
+
+```ruby
+interfax.documents.find(123456)
+=> #<InterFAX::Document ... >
+```
+
+**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2965)
+
+---
+
+### Cancel document
+
+`interfax.documents.cancel(id)`
+
+Cancel a document upload and tear down the upload session, or delete a previous upload.
+
+```ruby
+interfax.documents.cancel(123456)
+=> true
+```
+
+**More:** [none](https://www.interfax.net/en/dev/rest/reference/2964)
+
 ---
 
 ## Helper Classes
@@ -344,15 +451,21 @@ image.save('folder/fax.tiff') # Saves the TIFF to the path provided
 
 ### InterFAX::File
 
-This class is used by `interfax.outbound.deliver` to turn every URL, path and binary data into a uniform format, ready to be sent out to the InterFAX API.
+This class is used by `interfax.outbound.deliver` and `interfax.files` to turn every URL, path and binary data into a uniform format, ready to be sent out to the InterFAX API.
 
 It is most useful for sending binary data to the `.deliver` method.
 
 ```rb
 # binary data
-file = InterFAX::File.new('....binary data.....', mime_type: 'application/pdf')
-file.header #=> "Content-Type: application/pdf"
-file.body #=> '....binary data.....'
+file = InterFAX::File.new(interfax, '....binary data.....', mime_type: 'application/pdf')
+=> #<InterFAX::File>
+
+# Alternatively
+file = interfax.files.create('....binary data.....', mime_type: 'application/pdf')
+file.header
+=> "Content-Type: application/pdf"
+file.body
+=> '....binary data.....'
 
 interfax.outbound.deliver(faxNumber: '+1111111111112', file: file)
 ```
@@ -361,12 +474,12 @@ Additionally it can be used to turn a URL or path into a valid object as well, t
 
 ```rb
 # a file by path
-file = InterFAX::File.new('foo/bar.pdf')
+file = interfax.files.create('foo/bar.pdf')
 file.header #=> "Content-Type: application/pdf"
 file.body #=> '....binary data.....'
 
 # a file by url
-file = InterFAX::File.new('https://foo.com/bar.html')
+file = interfax.files.create('https://foo.com/bar.html')
 file.header #=> "Content-Location: https://foo.com/bar.html"
 file.body #=> nil
 ```
@@ -383,6 +496,18 @@ email.messageStatus # 0 = OK; number smaller than zero = in progress; number gre
 email.completionTime # Completion timestamp.
 ```
 
+### InterFAX::Document
+
+The `InterFAX::Document` is returned in most of the Document APIs. As a convenience the following methods are available.
+
+```ruby
+document = interfax.documents.find(123)
+document = document.reload # Loads or reloads object
+document.upload(0, 999, '.....binary data....' # Maps to the interfax.documents.upload method
+document.cancel # Maps to the interfax.documents.upload method
+document.id  # Extracts the ID from the URI (the API does not return the ID)
+```
+
 ## Contributing
 
  1. **Fork** the repo on GitHub

data/lib/interfax.rb

@@ -3,6 +3,7 @@ require 'interfax/client'
 require 'interfax/account'
 require 'interfax/object'
 require 'interfax/file'
+require 'interfax/files'
 require 'interfax/forwarding_email'
 require 'interfax/outbound'
 require 'interfax/outbound/fax'
@@ -10,5 +11,7 @@ require 'interfax/outbound/delivery'
 require 'interfax/inbound'
 require 'interfax/inbound/fax'
 require 'interfax/image'
+require 'interfax/document'
+require 'interfax/documents'
 
 require 'mimemagic'

data/lib/interfax/client.rb

@@ -10,7 +10,7 @@ module InterFAX
     class UnauthorizedError < StandardError; end
 
     attr_accessor :username, :password, :http
-    attr_writer :outbound, :inbound, :account
+    attr_writer :outbound, :inbound, :account, :documents, :files
 
     DOMAIN = "rest.interfax.net".freeze
     USER_AGENT = "InterFAX Ruby #{InterFAX::VERSION}".freeze
@@ -45,6 +45,14 @@ module InterFAX
       @inbound ||= InterFAX::Inbound.new(self)
     end
 
+    def documents
+      @documents ||= InterFAX::Documents.new(self)
+    end
+
+    def files
+      @files ||= InterFAX::Files.new(self)
+    end
+
     def get path, params = {}, valid_keys = {}
       uri = uri_for(path, params, valid_keys)
       request = Net::HTTP::Get.new(uri.request_uri)
@@ -61,6 +69,12 @@ module InterFAX
       transmit(request)
     end
 
+    def delete path
+      uri = uri_for(path)
+      request = Net::HTTP::Delete.new(uri.request_uri)
+      transmit(request)
+    end
+
     private
 
     def uri_for(path, params = {}, keys = {})

data/lib/interfax/document.rb

@@ -0,0 +1,17 @@
+class InterFAX::Document < InterFAX::Object
+  def upload range_start, range_end, chunk
+    client.documents.upload(id, range_start, range_end, chunk)
+  end
+
+  def cancel
+    client.documents.cancel(id)
+  end
+
+  def reload
+    client.documents.find(id)
+  end
+
+  def id
+    uri.split("/").last
+  end
+end

data/lib/interfax/documents.rb

@@ -0,0 +1,42 @@
+class InterFAX::Documents
+
+  def initialize client
+    @client = client
+  end
+
+  def create name, size, options = {}
+    options[:name] = name
+    options[:size] = size
+
+    valid_keys = [:name, :size, :disposition, :shared]
+    
+    uri = @client.post("/outbound/documents", options, valid_keys)
+    InterFAX::Document.new(uri: uri, client: @client)
+  end
+
+  def upload document_id, range_start, range_end, chunk
+    headers = { 'Range' => "bytes=#{range_start}-#{range_end}" }
+    @client.post("/outbound/documents/#{document_id}", {}, {}, headers, chunk)
+    true
+  end
+
+  def all options = {}
+    valid_keys = [:limit, :offset]
+    @client.get("/outbound/documents", options, valid_keys).map do |document|
+      document[:client] = @client
+      InterFAX::Document.new(document)
+    end
+  end
+
+  def find document_id
+    document = @client.get("/outbound/documents/#{document_id}")
+    document[:client] = @client
+    InterFAX::Document.new(document)
+  end
+
+  def cancel document_id
+    @client.delete("/outbound/documents/#{document_id}")
+    true
+  end
+
+end

data/lib/interfax/file.rb

@@ -1,7 +1,10 @@
 class InterFAX::File
-  attr_accessor :header, :body
+  attr_accessor :header, :body, :client, :chunk_size
+
+  def initialize client, location, options = {}
+    self.client = client
+    self.chunk_size = options[:chunk_size] || 1024*1024
 
-  def initialize location, options = {}
     if options[:mime_type]
       initialize_binary(location, options[:mime_type])
     elsif location.start_with?('http://') || location.start_with?('https://')
@@ -12,6 +15,7 @@ class InterFAX::File
   end
 
   def initialize_binary(data, mime_type)
+    return initialize_document(data, mime_type) if data.length > chunk_size
     self.header = "Content-Type: #{mime_type}"
     self.body = data
   end
@@ -23,9 +27,30 @@ class InterFAX::File
 
   def initialize_path(path)
     file = File.open(path)
-    mime_type = MimeMagic.by_magic(file)
+    mime_type = MimeMagic.by_magic(file) || MimeMagic.by_path(file)
+    data = File.open(path, 'rb').read
 
-    self.header = "Content-Type: #{mime_type}"
-    self.body = File.open(path, 'rb').read
+    initialize_binary(data, mime_type)
+  end
+
+  def initialize_document(data, mime_type)
+    document = create_document(data, mime_type)
+    upload(document, data)
+    initialize_url(document.uri)
+  end
+
+  def upload document, data
+    cursor = 0
+    data.bytes.each_slice(chunk_size) do |slice|
+      chunk = slice.pack("C*")
+      next_cursor = cursor + chunk.length
+      document.upload(cursor, next_cursor - 1, chunk)
+      cursor = next_cursor
+    end
+  end
+
+  def create_document data, mime_type
+    extension = MimeMagic::EXTENSIONS.select {|k,v| v == mime_type.to_s}.keys.first
+    client.documents.create("upload-#{Time.now.to_i}.#{extension}", data.length)
   end
 end

data/lib/interfax/files.rb

@@ -0,0 +1,9 @@
+class InterFAX::Files
+  def initialize client
+    @client = client
+  end
+
+  def create data, options = {}
+    InterFAX::File.new(@client, data, options)
+  end
+end

data/lib/interfax/outbound/delivery.rb

@@ -37,7 +37,7 @@ class InterFAX::Outbound::Delivery
   def generate_file_objects files
     files.map do |file|
       if file.kind_of?(String)
-        InterFAX::File.new(file)
+        InterFAX::File.new(client, file)
       elsif file.kind_of?(InterFAX::File)
         file
       end

data/lib/interfax/version.rb

@@ -1,3 +1,3 @@
 module InterFAX
-  VERSION = '1.0.0.beta.1'
+  VERSION = '1.0.0.beta.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: interfax
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta.1
+  version: 1.0.0.beta.2
 platform: ruby
 authors:
 - InterFAX
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-08-01 00:00:00.000000000 Z
+date: 2016-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mimemagic
@@ -95,7 +95,10 @@ files:
 - lib/interfax.rb
 - lib/interfax/account.rb
 - lib/interfax/client.rb
+- lib/interfax/document.rb
+- lib/interfax/documents.rb
 - lib/interfax/file.rb
+- lib/interfax/files.rb
 - lib/interfax/forwarding_email.rb
 - lib/interfax/image.rb
 - lib/interfax/inbound.rb