oshpark 0.0.10 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9c03c63de755a320ca2ff92012a6ee518224a36d
-  data.tar.gz: fb4a13cb27455eca130da96a42e00af4c8410741
+  metadata.gz: 2834c0fd61a309e742ba08525f37bae1684edbf7
+  data.tar.gz: 2451a5be624a54730515bf42e9d3ea6aaf341485
 SHA512:
-  metadata.gz: 6a82622645351c80fbb0728cafcbba2c1d887d3dd122cead3223a6b2bd98e9bc63bdc3a69938d671bd5aeae0d5e88cf78c8dd163019fb42ba99cfa9256fd3026
-  data.tar.gz: bb2392fedfcf1ea183e65c057536ea50ecfbab3a1f91586d3ae8825ab017398b523ee2f4c48812aa1f82bf0c37fb99e3a33ca67381a3206c5ee650c9595ea1be
+  metadata.gz: c7c9ecd5dc76fb44de77dff1f164201214094fab534d67e28aa72d8445570864041f3928377e660b27a0e124e09ba16ff0d40a44d1ec45625b24c8d676fa2386
+  data.tar.gz: ad0be34d9762b290fc4676459a139c858a01123a740038b2d02e056d1398ac0f702af3348d7a3dc72200d1533988d1e9f4bbf7039e309bf88475579ef4a6701a

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    oshpark (0.0.10)
+    oshpark (1.0.0)
       micro_token
       thor
 

data/README.md

@@ -1,78 +1,231 @@
-# Oshpark
+# OSH Park
 ##An electric ecosystem
 
 [ ![Codeship Status for OSHPark/ruby-api-client](https://codeship.io/projects/a0abc8d0-d247-0131-3eb6-7653b9bc7be9/status?branch=master)](https://codeship.io/projects/23318)
 
 [OSH Park](https://oshpark.com) is a community printed circuit board (PCB) order.
-The Oshpark gem allows developers to easily access the Oshpark API. Developer resources can be found at [https://oshpark.com/developer](https://oshpark.com/developer)
+The OSH Park gem allows developers to easily access the OSH Park API. Developer resources can be found at [https://oshpark.com/developer](https://oshpark.com/developer)
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'oshpark'
+```ruby
+gem 'oshpark'
+```
 
 And then execute:
 
-    $ bundle
+```sh
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install oshpark
+```sh
+$ gem install oshpark
+```
 
 ## Usage
 
-Before you begin you need to have an [Oshpark account](http://oshpark.com/users/sign_up) and then request access to the Oshpark API. Do this by contacting ????
+Before you begin you need to have an [OSH Park account](http://oshpark.com/users/sign_up) and then request access to the OSH Park API. Do this by contacting [OSH Park support](mailto:support@oshpark.com)
 
-This gem provides two interfaces to the OShpark API.
+This gem provides two interfaces to the OSH Park API.
 
 ### Low level API
 
-For use when you have an ORM, framework or pre-exsiting classes that you want to load the Oshpark data into.
+For use when you have an ORM, framework or pre-exsiting classes that you want to load the OSH Park data into.
 
-The API consists of a number of methods that map to the methods exposed by the Oshpark REST API. These methods take Ruby hashes representing the request data and return hashes of the API responses. Refer to [https://oshpark.com/developer/resources](https://oshpark.com/developer/resources) for details.
+The API consists of a number of methods that map to the methods exposed by the OSH Park REST API. These methods take Ruby hashes representing the request data and return hashes of the API responses. Refer to [https://oshpark.com/developer/resources](https://oshpark.com/developer/resources) for details.
 
-First create an Oshpark::client object and authenticate;
+First create an `Oshpark::client` object and authenticate;
 
-    client = Oshpark::client
-    client.authenticate 'jane@resistor.io', {with_password: 'secret'}
+```ruby
+client = Oshpark::client
+client.authenticate 'jane@resistor.io', with_password: 'secret'
+```
 
-Then you can can use this object to interact with Oshpark;
+Then you can can use this object to interact with OSH Park;
 
-    file = File.open('my_pcb.zip', 'r')
-    upload = client.create_upload file
-    ...
-    my_projects = client.projects
-    ...
-    project = client.project 'id'
-    client.update_project project["id"], {"name" => "my awesome project"}
-    ...
-    new_order = client.create_order
-    ...
+```ruby
+file = File.open('my_pcb.zip', 'r')
+upload = client.create_upload file
+# ...
+my_projects = client.projects
+# ...
+project = client.project 'id'
+client.update_project project["id"], {"name" => "my awesome project"}
+# ...
+new_order = client.create_order
+# ...
+```
 
-All low level methods will call to Oshpark's servers. Refer to the [source documentation](http://www.rubydoc.info/github/OSHPark/ruby-api-client/master) for more detailed information on each of the available methods.
+All low level methods will call to OSH Park's servers. Refer to the [source documentation](http://www.rubydoc.info/github/OSHPark/ruby-api-client/master) for more detailed information on each of the available methods.
 
 ### High Level API
 
-This is more suited to when you are writing a script or application and you want to use Ruby objects to represent the Oshpark data. It uses the Low Level API underneath but wraps the return data in nice Ruby objects.
+This is more suited to when you are writing a script or application and you want to use Ruby objects to represent the OSH Park data. It uses the Low Level API underneath but wraps the return data in nice Ruby objects.
 
-Again begin by creating an Oshpark::client and authenticating;
+#### Authenticate
 
-    client = Oshpark::client
-    client.authenticate 'jane@resistor.io', {with_password: 'secret'}
+```ruby
+client = Oshpark::client
+client.authenticate 'jane@resistor.io', with_password: 'secret'
+```
 
-    file = File.open('my_pcb.zip', 'r')
-    upload = Oshpark::Upload.create file
-    ...
-    my_projects = Oshpark::Project.all
-    ...
-    project = Oshpark::Project.find 'id'
-    project.name = "my awesome project"
-    project.save!
-    ...
-    new_order = Oshpark::Order.create
-    ...
+or with your API secret if you have one:
 
+```ruby
+client = Oshpark::client
+client.authenticate 'jane@resistor.io', with_api_secret: 'secret'
+```
+
+##### Creating Your Project
+
+Next you need to get your project into OSH Park.  This is done by either
+uploading a file or importing a file from a URL.
+
+###### Upload
+
+To upload a file directly to the API you create an `Oshpark::Upload` object by
+passing in an `IO` object:
+
+```ruby
+file   = File.open 'my_pcb.zip'
+upload = Oshpark::Upload.create file
+file.close
+```
+
+You now need to wait for processing of the file to complete:
+
+```ruby
+until upload.finished?
+  sleep 1
+  upload.reload!
+end
+```
+
+Now you can access your project via the upload's `project` method:
+
+```ruby
+project = upload.project
+```
+
+###### Import
+
+Importing from a remote URL is almost exactly the same as uploading, except
+that you create an instance of the `Oshpark::Import` object, and monitor it
+in much the same was as upload:
+
+```ruby
+import = Oshpark::Upload.create 'https://example.com/my_pcb.zip'
+```
+
+You now need to wait for processing of the file to complete:
+
+```ruby
+until import.finished?
+  sleep 1
+  import.reload!
+end
+```
+
+Now you can access your project via the import's `project` method:
+
+```ruby
+project = import.project
+```
+
+##### Verifying your project
+
+Next you need to verify that your board has been processed as expected.
+Start by verifying that the `top_image` and `bottom_image` match your
+expectations and verify that all the `layers` that you expect are present
+with their image files.
+
+Once you are certain that we have processed your board correctly, then you
+can approve it for ordering:
+
+```ruby
+project.approve
+```
+
+##### Ordering your project
+
+There are a few steps to go through before you can order your board (or boards)
+via the API:
+
+###### Create a new order
+
+The first step is to create a new, empty order into which you will add your items:
+
+```ruby
+order = Oshpark::Order.create
+```
+
+###### Add your project(s) to your order
+
+Next you need to add your project(s) to your order, specifying their quantity.
+Remember that for prototype services quantities must be in multiples of three.
+
+```ruby
+order.add_item project, 3
+```
+
+###### Create an address
+
+Create an address object with your delivery details:
+
+```ruby
+address = Oshpark::Address.new \
+  name:               'Jane Doe',
+  company_name:       'Resistor Ltd',
+  address_line_1:     'Level One, 83-85 Victoria Road',
+  address_line_2:     'Devonport',
+  city:               'Auckland',
+  zip_or_postal_code: '0624',
+  country:            'nz'
+```
+
+###### Set your order address
+
+Once you have generated your address, you can set it on the order:
+
+```ruby
+order.set_address address
+```
+
+###### Get and set the shipping rates
+
+As our shipping providers generate individual pricing for each destination
+address you need to ask the API to retrieve all the available rates for your
+address.  The available rates will always include the USPS free shipping
+options.
+
+```ruby
+rates = address.available_shipping_rates
+```
+
+Set your order to one of the provided shipping rates:
+
+```ruby
+order.set_shipping_rate rates.first
+```
+
+###### Checkout your order
+
+Next you should be able to checkout your order:
+
+```ruby
+order.checkout
+```
+
+If you are an invoiced customer then your order will immediately be placed in
+the queue ready for panelization, otherwise you will get an email asking for
+payment before the order can continue.  We can't accept credit card payments
+via the API at this time.
+
+If you are not, but would like to be an invoiced customer then contact [OSH Park support](mailto:support@oshpark.com).
 
 ## Contributing
 

data/lib/oshpark/client.rb

@@ -59,7 +59,6 @@ module Oshpark
     # Approve a particular project from the current user's collection by ID.
     # We strongly suggest that you allow the user to view the rendered images
     # in Project#top_image, Project#bottom_image and Project#layers[]#image
-    # You should probably call Project#approve! instead.
     #
     # @param id
     def approve_project id
@@ -123,6 +122,7 @@ module Oshpark
     #
     # @param id
     # @param address
+    # An Address object or a Hash with at least the required keys: :name :address_line_1 :address_line_2 :city :country
     def set_order_address id, address
       post_request "orders/#{id}/set_address", {order: {address: address.to_h}}
     end
@@ -134,10 +134,10 @@ module Oshpark
     # Set the delivery address for an Order
     #
     # @param id
-    # @param carrier_name
-    # @param service_name
-    def set_order_shipping_rate id, carrier_name, service_name
-      post_request "orders/#{id}/set_shipping_rate", {order:{shipping_rate:{carrier_name: carrier_name, service_name: service_name}}}
+    # @param shipping_rate
+    # A ShippingRate object or a Hash with the following keys: :carrier_name :service_name
+    def set_order_shipping_rate id, shipping_rate
+      post_request "orders/#{id}/set_shipping_rate", {order:{shipping_rate: shipping_rate.to_h}}
     end
 
     # Checkout a specific order by ID.

data/lib/oshpark/connection.rb

@@ -4,9 +4,11 @@ require 'net/http'
 require 'micro_token'
 
 module Oshpark
-  Unauthorized = Class.new(RuntimeError)
-  NotFound     = Class.new(RuntimeError)
-  ServerError  = Class.new(RuntimeError)
+  HttpError     = Class.new RuntimeError
+  Unauthorized  = Class.new HttpError
+  NotFound      = Class.new HttpError
+  ServerError   = Class.new HttpError
+  Unprocessable = Class.new HttpError
 
   class Connection
     def initialize endpoint_url
@@ -47,11 +49,15 @@ module Oshpark
 
       case response.code.to_i
       when 401
-        raise Unauthorized, json['error']
+        raise Unauthorized,  json['error']
       when 404
-        raise NotFound,     json['error']
+        raise NotFound,      json['error']
+      when 422
+        raise Unprocessable, json['error']
+      when 400...499
+        raise HttpError,     json['error']
       when 500...599
-        raise ServerError,  json['error']
+        raise ServerError,   json['error']
       end
 
       json

data/lib/oshpark/model.rb

@@ -77,6 +77,7 @@ module Oshpark
         end
         @dirty_attributes = []
       end
+      self
     end
 
     def guard_against_invalid_arguments keys

data/lib/oshpark/order.rb

@@ -20,29 +20,23 @@ module Oshpark
     end
 
     def add_item order_item, quantity
-      json = Oshpark::client.add_order_item id, order_item.id, quantity
-      reload_with json
+      reload_with Oshpark::client.add_order_item id, order_item.id, quantity
     end
 
     def set_address address
-      json = Oshpark::client.set_order_address id, address
-      reload_with json
+      reload_with Oshpark::client.set_order_address id, address
     end
 
-    def set_shipping_rate *args
-      carrier_name, service_name = if Oshpark::ShippingRate === args.first
-                                     rate = args.first
-                                     [rate.carrier_name, rate.service_name]
-                                   else
-                                     args
-                                   end
-      json = Oshpark::client.set_order_shipping_rate id, carrier_name, service_name
-      reload_with json
+    def set_shipping_rate shipping_rate
+      reload_with Oshpark::client.set_order_shipping_rate id, shipping_rate
     end
 
     def checkout
-      json = Oshpark::client.checkout_order id
-      reload_with json
+      reload_with Oshpark.client.checkout_order id
+    end
+
+    def cancel
+      reload_with Oshpark.client.cancel_order id
     end
 
     def panel

data/lib/oshpark/project.rb

@@ -45,9 +45,8 @@ module Oshpark
       @height_in_mils || 0
     end
 
-    def approve!
-      json = Oshpark::client.approve_project id
-      reload_with json
+    def approve
+      reload_with Oshpark::client.approve_project id
     end
 
   end

data/lib/oshpark/shipping_rate.rb

@@ -14,5 +14,10 @@ module Oshpark
         from_json shipping_rate_json
       end
     end
+
+    def to_h
+      {carrier_name: carrier_name, service_name: service_name}
+    end
+
   end
 end

data/lib/oshpark/version.rb

@@ -1,3 +1,3 @@
 module Oshpark
-  VERSION = "0.0.10"
+  VERSION = "1.0.0"
 end

data/oshpark.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["james@resistor.io", "henry@resistor.io"]
   spec.summary       = %q{API and command line client for oshpark.com}
   spec.description   = %q{API and command line client for PCB fabrication via oshpark.com}
-  spec.homepage      = ""
+  spec.homepage      = "https://github.com/oshpark/ruby-api-client"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0")

data/spec/acceptance/workflow_spec.rb

@@ -35,7 +35,7 @@ describe 'API Workflow' do
     expect(project.layers.size).to eq 7
     expect(project.layers.all? { |l| l.class == Oshpark::Layer }).to eq true
 
-    project.approve!
+    project.approve
 
     expect(project).to be_approved
 
@@ -64,8 +64,7 @@ describe 'API Workflow' do
     order.set_shipping_rate rates.first
     expect(order.shipping_rate).to be
 
-    # order.checkout
-    # expect(order).to be_processing
-    puts Oshpark.client.checkout_order(order.id).inspect
+    order.checkout
+    expect(order).to be_received
   end
 end