doxie 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: b397c377274d4870e902d85ae5e2b58045f35816
-  data.tar.gz: 9b8346d5b0e6420622ca033ca9341c101b2feeca
+SHA256:
+  metadata.gz: 86ca65be716261fc75507c33432181058e8c567be9e9c8f34e88b884222822be
+  data.tar.gz: 2686549b36f731522f3f7c11c505f9c57dbb2ff5e1d8cac461b2827d2a535b90
 SHA512:
-  metadata.gz: 43c469dfc64dea3f032ad43743406fdc3bcc464b55b1f742e26b48d9557bc1df13f1af769b84dd823facb08f11d41bbdc5a623949522bfb12618acf1c6fbf9aa
-  data.tar.gz: 9b0bfcdb9a2ad6df382fbeaa3950b257d631fb3369491432e7619f03194317f092c9ac2c197c26ecb5b78ca897bdeb93a27e2c54d72f6341c2a4a27362cc0279
+  metadata.gz: 87d150d0d5fc9cf79c06e3aa6726d92c3a1eaf83c8208043f4dd512f79f32af37512402a83919a095769ec63ba80722df70f83b225a00eb6ffe32cf60bb3fae7
+  data.tar.gz: b3b46c8ceb2128959117a7ca2502da83cf77ff3afece80acd563d95f849dd58ba6f42b31bef641770edd6cd80ef23578ab048cbbda5fe521f77c119ba8792f2b

data/README.md

@@ -2,7 +2,15 @@
 
 [![Gem Version](https://badge.fury.io/rb/doxie.svg)](https://badge.fury.io/rb/doxie) [![Build Status](https://travis-ci.org/cbetta/doxie.svg?branch=master)](https://travis-ci.org/cbetta/doxie)
 
-A wrapper for the [Doxie Go Wifi](http://getdoxie.com) API. Specification as per the [developer documentation](http://help.getdoxie.com/content/doxiego/05-advanced/03-wifi/04-api/Doxie-API-Developer-Guide.pdf).
+A client library for the API available on WiFi-enabled [Doxie scanners](http://getdoxie.com). The specification of the API is available in their [developer documentation](/docs).
+
+## Scanners Supported
+
+This library supports the following scanners:
+
+* Doxie Go Wifi (DX250)
+* Doxie Go SE (DX255)
+* Doxie Q (DX300)
 
 ## Installation
 
@@ -15,9 +23,9 @@ gem 'doxie-scanner' # optional if your Doxie is not on a fixed IP
 
 ## Usage
 
-### Finding your Doxie
+### Optional: Finding your Doxie's IP
 
-This requires the [`doxie_scanner`](https://github.com/cbetta/doxie_scanner) gem. This gem has a bigger dependency than the `doxie` gem which is why it has been split into a seperate library.
+This optional step requires the [`doxie-scanner`](https://github.com/cbetta/doxie-scanner) gem. This gem has a bigger dependency than the `doxie` gem, which is why it has been intentionally separated into a seperate library.
 
 ```rb
 require 'doxie/scanner'
@@ -29,14 +37,29 @@ Doxie::Scanner.ips
 
 ### Client
 
-The client accepts an `ip` and `password`. You can omit the `password` if your Doxie has non set.
+The client accepts an `ip` address, a scanner model number (defaults to `Doxie::GO`) and an optional `password`. You can omit the `password` if your Doxie has non set.
 
 ```rb
 require 'doxie'
-client = Doxie::Client.new(ip: '192.168.1.2', password: 'test')
+client = Doxie::Client.new(
+    ip: '192.168.1.2', 
+    model: Doxie::Q, # of Doxie::GO, or Doxie::GO_SE
+    password: 'test'
+)
 ```
 
-### GET /hello.json
+Alternatively, you can use the [`doxie-scanner`](https://github.com/cbetta/doxie-scanner) gem to automatically connect to any scanner found. 
+
+```rb
+require 'doxie'
+require 'doxie/scanner'
+
+client = Doxie::Client.new(
+  Doxie::Scanner.devices.first
+)
+```
+
+### `GET /hello.json`
 
 Returns status information for the scanner, firmware, network mode, and password
 configuration. Accessing this command does not require a password if one has been
@@ -57,22 +80,22 @@ client.hello
 }
 ```
 
-* __model__: Always DX250.
-* __name__: The name of the scanner, which defaults to the form "Doxie_XXXXXX".
+* `model`: DX250 for the Doxie Go WiFi.
+* `name`: The name of the scanner, which defaults to the form "Doxie_XXXXXX".
   The name of a scanner can be changed by using the Doxie desktop app.
-* __firmwareWiFi__: The Wi-Fi firmware version.
-* __hasPassword__: Indicates whether a password has been set to authenticate API
+* `firmwareWiFi`: The Wi-Fi firmware version.
+* `hasPassword`: Indicates whether a password has been set to authenticate API
   access. Passwords can be set and removed by using the Doxie desktop app.
-* __MAC__: The MAC address of the scanner as shown on the scanner's bottom
+* `MAC`: The MAC address of the scanner as shown on the scanner's bottom
   label.
-* __mode__: "AP" if the scanner is creating its own network or "Client" if the
+* `mode`: "AP" if the scanner is creating its own network or "Client" if the
   scanner is joining an existing network.
-* __network__: If the scanner is in "Client" mode, this is the name of the
+* `network`: If the scanner is in "Client" mode, this is the name of the
   network it has joined.
-* __ip__: If the scanner is in "Client" mode, this is the IP of the scanner on
+* `ip`: If the scanner is in "Client" mode, this is the IP of the scanner on
   the network it has joined.
 
-### GET /hello_extra.json
+### `GET /hello_extra.json`
 
 Returns additional status values. These values are accessed separately from
 those in `/hello.json` because there can be a delay of several seconds in
@@ -87,12 +110,14 @@ client.hello_extra
 }
 ```
 
-* __firmware__: The scanner firmware version.
-* __connectedToExternalPower__: Indicates whether the scanner is connected to
+* `firmware`: The scanner firmware version.
+* `connectedToExternalPower`: Indicates whether the scanner is connected to
   its AC adapter versus running on battery power. This value is not cached, so
   it immediately reflects any state changes.
 
-### GET /restart.json
+This method is only available for the original Doxie Go WiFi model.
+
+### `GET /restart.json`
 
 Restarts the scanner's Wi-Fi system. The scanner's status light blinks blue
 during the restart.
@@ -102,7 +127,7 @@ client.restart
 => true
 ```
 
-### GET /scans.json
+### `GET /scans.json`
 
 Returns an array of all scans currently in the scanner’s memory. After scanning
 a document, the scan will available via the API several second later.
@@ -123,7 +148,7 @@ result, even if there are other scans on the scanner, due to the scanner's
 memory being in use. Consider retrying if a successful HTTP status code is
 returned along with a blank body.
 
-### GET /scans/recent.json
+### `GET /scans/recent.json`
 
 Returns the path to the last scan if available. Monitoring this value for
 changes provides a simple way to detect new scans without having to fetch the
@@ -136,7 +161,7 @@ client.recent_scans
 }
 ```
 
-### GET /scans/DOXIE/JPEG/IMG_XXXX.JPG
+### `GET /scans/DOXIE/JPEG/IMG_XXXX.JPG`
 
 There are 2 ways to get a scan off your Doxie. The first is to get the raw binary content and then do something with it yourself.
 
@@ -152,7 +177,7 @@ client.scan "/DOXIE/JPEG/IMG_0001.JPG", 'test.jpg'
 => true
 ```
 
-### GET /thumbnails/DOXIE/JPEG/IMG_XXXX.JPG
+### `GET /thumbnails/DOXIE/JPEG/IMG_XXXX.JPG`
 
 There are 2 ways to get a thumbnail off your Doxie. The first is to get the raw binary content and then do something with it yourself.
 
@@ -174,7 +199,7 @@ scans are not generated until after the scan has been made available in
 if the thumbnail has not yet been generated. Retrying after a delay is
 recommended to handle such cases.
 
-### DELETE /scans/DOXIE/JPEG/IMG_XXXX.JPG
+### `DELETE /scans/DOXIE/JPEG/IMG_XXXX.JPG`
 
 Deletes the scan at the specified path.
 
@@ -188,7 +213,9 @@ obtained and released. Deleting may fail if the lock cannot be obtained
 (e.g., the scanner is busy), so consider retrying on failure conditions. When
 deleting multiple scans, use `/scans/delete.json` for best performance.
 
-### POST /scans/delete.json
+This will raise an error if the file is no longer present (`Doxie::Client::Error<Net::HTTPForbidden>`)
+
+### `POST /scans/delete.json`
 
 Deletes multiple scans in a single operation. This is much faster than deleting
 each scan individually.
@@ -198,6 +225,8 @@ client.delete_scans ["/DOXIE/JPEG/IMG_0001.JPG", "/DOXIE/JPEG/IMG_0002.JPG"]
 => true
 ```
 
+This will raise an error if the files are no longer present (`Doxie::Client::Error<Net::HTTPForbidden>`)
+
 ## Contributing
 
  1. **Fork** the repo on GitHub

data/lib/doxie.rb

@@ -1,2 +1,3 @@
 require 'doxie/version'
+require 'doxie/models'
 require 'doxie/client'

data/lib/doxie/client.rb

@@ -5,17 +5,19 @@ module Doxie
   # The client for connecting to a Doxie scanner.
   #
   # Use the IP and password to connect as follows:
-  #   Doxie::Client.new(ip: '192.168.1.2', password: 'test')
+  #   Doxie::Client.new(ip: '192.168.1.2', model: Doxie::Q, password: 'test')
   class Client
     class Error < StandardError; end
 
     USERNAME = 'doxie'.freeze
 
-    attr_accessor :ip, :password
+    attr_accessor :ip, :password, :model, :port
 
     def initialize(options)
       @ip = options[:ip] || ''
       @password = options[:password] || ''
+      @model = options[:model] || Doxie::API_V1
+      @port = @model ==  Doxie::API_V1 ? 8080 : 80
     end
 
     def hello
@@ -23,19 +25,25 @@ module Doxie
     end
 
     def hello_extra
+      raise Error.new('Method does not exist for this model') if model ==  Doxie::API_V2
       get('/hello_extra.json')
     end
 
     def restart
-      get('/restart.json')
+      get('/restart.json') || true
     end
 
     def scans
       get('/scans.json')
+    rescue Doxie::Client::Error => error
+      # a 404 is thrown on the Doxie Q and 
+      # Doxie GO SE when there are no scans
+      raise error if model == Doxie::DX250
+      [] 
     end
 
     def recent_scans
-      get('/scans/recent.json')
+      get('/scans/recent.json') || []
     end
 
     def scan(scan_name, file_name = nil)
@@ -47,11 +55,11 @@ module Doxie
     end
 
     def delete_scan(scan_name)
-      delete("/scans#{scan_name}")
+      delete("/scans#{scan_name}") || true
     end
 
     def delete_scans(scan_names)
-      post('/scans/delete.json', scan_names)
+      post('/scans/delete.json', scan_names) || true
     end
 
     private
@@ -76,11 +84,11 @@ module Doxie
     end
 
     def uri_for(path)
-      URI("https://#{ip}:8080#{path}")
+      URI("http://#{ip}:#{port}#{path}")
     end
 
     def request(uri, message)
-      message.basic_auth USERNAME, password if password
+      message.basic_auth USERNAME, password if password && password.length > 0
       http = Net::HTTP.new(uri.host, uri.port)
       http.request(message)
     end
@@ -88,7 +96,7 @@ module Doxie
     def parse(response)
       case response
       when Net::HTTPNoContent
-        true
+        nil
       when Net::HTTPSuccess
         parse_json(response)
       else

data/lib/doxie/models.rb

@@ -0,0 +1,12 @@
+module Doxie
+  API_V1 = 'API_V1'.freeze
+  API_V2 = 'API_V2'.freeze
+
+  DX250 = API_V1
+  DX255 = API_V2
+  DX300 = API_V2
+
+  GO    = API_V1
+  GO_SE = API_V2  
+  Q     = API_V2
+end

data/lib/doxie/version.rb

@@ -1,3 +1,3 @@
 module Doxie
-  VERSION = '2.0.0'.freeze
+  VERSION = '3.0.0'.freeze
 end

data/spec/doxie_spec.rb

@@ -18,9 +18,22 @@ describe 'Doxie::Client' do
     @json_response_body = json_response_body('{"key":"value"}')
     @ip = '192.168.1.1'
     @base_url = "http://#{@ip}:8080"
+    @base_url_v2 = "http://#{@ip}:80"
     @client = Doxie::Client.new(ip: @ip)
   end
 
+  describe 'Doxie Models' do
+    it 'should assign the right values to each model' do
+      assert_equal Doxie::GO, Doxie::API_V1
+      assert_equal Doxie::DX250, Doxie::API_V1
+
+      assert_equal Doxie::Q, Doxie::API_V2
+      assert_equal Doxie::GO_SE, Doxie::API_V2
+      assert_equal Doxie::DX255, Doxie::API_V2
+      assert_equal Doxie::DX300, Doxie::API_V2
+    end
+  end 
+
   describe 'get /hello.json' do
     it 'should return the result' do
       stub_request(:get, "#{@base_url}/hello.json")
@@ -35,6 +48,12 @@ describe 'Doxie::Client' do
         .to_return(@json_response_body)
       @client.hello_extra.must_equal(@json_response_object)
     end
+
+    it 'should error for API V2 models, as the method does not exist' do
+      @client = Doxie::Client.new(ip: @ip, model: Doxie::API_V2)
+      error = -> { @client.hello_extra }.must_raise(Doxie::Client::Error)
+      error.message.must_match "Method does not exist for this model"
+    end
   end
 
   describe 'get /restart.json' do
@@ -51,6 +70,13 @@ describe 'Doxie::Client' do
         .to_return(@json_response_body)
       @client.scans.must_equal(@json_response_object)
     end
+
+    it 'should return an empty array when there are no scans on a V2 model' do
+      @client = Doxie::Client.new(ip: @ip, model: Doxie::API_V2)
+      stub_request(:get, "#{@base_url_v2}/scans.json")
+        .to_return(status: 404)
+      @client.scans.must_equal([])
+    end
   end
 
   describe 'get /scans/recent.json' do
@@ -59,6 +85,13 @@ describe 'Doxie::Client' do
         .to_return(@json_response_body)
       @client.recent_scans.must_equal(@json_response_object)
     end
+
+    it 'should return an empty array when there are no scans on a V2 model' do
+      @client = Doxie::Client.new(ip: @ip, model: Doxie::API_V2)
+      stub_request(:get, "#{@base_url_v2}/scans/recent.json")
+        .to_return(status: 204)
+      @client.recent_scans.must_equal([])
+    end
   end
 
   describe 'get /scans/DOXIE/JPEG/IMG_0001.JPG' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: doxie
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Cristiano Betta
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-10-06 00:00:00.000000000 Z
+date: 2019-01-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -77,6 +77,7 @@ files:
 - doxie.gemspec
 - lib/doxie.rb
 - lib/doxie/client.rb
+- lib/doxie/models.rb
 - lib/doxie/version.rb
 - spec/doxie_spec.rb
 homepage: https://github.com/cbetta/doxie
@@ -98,8 +99,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.13
+rubygems_version: 3.0.2
 signing_key: 
 specification_version: 4
 summary: Doxie API Wrapper for getting scans off your Doxie scanner