printfection 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 988cf5fbd90dab60a47312201529a4a7c2b4c8db
+  data.tar.gz: 1ad04c530a77b106a8e0fe8c9a834d8eda1e4a48
+SHA512:
+  metadata.gz: e609441046a5bd41cfbce861c1c296257104b3ce6b1c233f40fb59125794b8dc8cf7f89c108f0e350df301b8695bd0b770ae8b97f1055555bc036a54cf120730
+  data.tar.gz: a79796194853ee8cedfa0bdf06f06e4f348dc03fa73b64d2132fea0372a68028556bab67d8710ba5a3983183885953c99aa3600e20a8c3a537b16c1be7b4571b

data/.gitignore

@@ -0,0 +1,16 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.DS_Store
+

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,14 @@
+language: ruby
+rvm:
+  - ruby-head
+  - ruby-2.0.0-p598
+  - ruby-1.9.3-p551
+  - jruby-head
+  - jruby-19mode
+notifications:
+  recipients:
+    - rubygems@printfection.com
+addons:
+  code_climate:
+    repo_token: f5302e71ac67e807b7762e7ac743d2779841a422ab5c2cf1e7c7c34b6c080881
+

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+gemspec
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Printfection LLC
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,247 @@
+# Printfection Ruby API [![Build Status](https://travis-ci.org/Printfection/printfection-ruby.png?branch=prerelease)](https://travis-ci.org/Printfection/printfection-ruby) [![Code Climate](https://codeclimate.com/github/Printfection/printfection-ruby/badges/gpa.svg)](https://codeclimate.com/github/Printfection/printfection-ruby) [![Test Coverage](https://codeclimate.com/github/Printfection/printfection-ruby/badges/coverage.svg)](https://codeclimate.com/github/Printfection/printfection-ruby)
+
+Implementation of the [Printfection API](http://printfection.github.io/API-Documentation) for Ruby.
+
+At a high level, the Printfection API can be used to create, modify, place, and cancel orders. `Orders` are made up of a set of line items and a shipping address, but orders also expose detailed information about their products, sizes, assets, quantities, and availability.
+
+`Campaigns` are logical groups of items used to organize your orders. Orders are always associated to exactly one campaign, and only items associated to a given campaign can be placed in an order in the same campaign. For example, your company's marketing department might have a Giveaway campaign with coffee mugs to reward loyal customers, and your engineering department might have a Purchase campaign with nerdy swag to outfit new hires.
+
+Some campaigns have special abilities. Orders in `giveaway` and `freeforall` campaigns have a code and a web URL that can be used to redeem (i.e. place) that order. Orders in `freeforall` campaigns can be a gift and include a gift message.
+
+You can read the full API documentation and object reference [here](http://printfection.github.io/API-Documentation/#campaigns).
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'printfection'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install printfection
+
+
+## Usage
+
+First, configure your API token. This can be found in your account on [printfection.com](http://printfection.com).
+
+```ruby
+require "printfection"
+
+Printfection.api_token = "e3ce1ddf152d5533ca4a3d3543006bac6d57b2ac"
+```
+
+If you're using Rails, `config/initializers/printfection.rb` is a good place for this.
+
+### Retrieving an order
+
+```ruby
+order = Printfection::Order.retrieve(5)
+```
+
+### Listing all orders
+
+```ruby
+orders = Printfection::Order.all
+orders = Printfection::Order.all limit: 5, offset: 10
+```
+
+By default, list calls are automatically paginated and limited to 100 objects per request.
+
+
+### Creating an order
+
+At a minimum, a new order can be created with just a `campaign_id`:
+
+```ruby
+order = Printfection::Order.create(campaign_id: 1)
+  #=> #<Printfection::Order id: 1, campaign_id: 1>
+```
+
+Once you have created an order, you can then begin adding line items. A line item requires an `item_id`, `quantity`, and a `size_id` if the item has sizes.
+
+```ruby
+# Creating a line item with a size.
+order.line_items.create(
+  item_id: 1,
+  size_id: 2,
+  quantity: 3
+)
+  #=> #<Printfection::LineItem id: 1, order_id: 1, item_id: 1, size_id: 2, quantity: 3>
+
+# Creating a line item without a size.
+order.line_items.create(
+  item_id: 2,
+  quantity: 6
+)
+  #=> #<Printfection::LineItem id: 2, order_id: 1, item_id: 2, quantity: 6>
+
+```
+
+You can retrieve existing line items to update them:
+
+```ruby
+line_item = order.line_items.retrieve(1)
+  #=> #<Printfection::LineItem id: 1, order_id: 1, item_id: 1, quantity: 3>
+
+line_item.quantity = 12
+line_item.save
+  #=> true
+
+line_item.quantity
+  #=> 12
+```
+
+And delete them:
+
+```ruby
+line_item = order.line_items.retrieve(2)
+  #=> #<Printfection::LineItem id: 2, order_id: 1, item_id: 2, quantity: 6>
+
+line_item.delete
+  #=> true
+```
+
+Provide a shipping address for the order.
+
+```ruby
+order = Printfection::Order.retrieve(1)
+  #=> #<Printfection::Order id: 1 ...>
+
+order.ship_to = {
+  name: "Joseph Schmo",
+  address: "123 Main Street",
+  address2: "Suite 101",
+  company: "ACME Inc.",
+  city: "Denver",
+  state: "Colorado",
+  zip: "80202",
+  country: "United States"
+}
+
+order.save
+  #=> true
+```
+
+Whoops, that should be shipped to Sally.
+
+```ruby
+order.ship_to.name = "Sally Schmo"
+order.save
+  #=> true
+```
+
+Finally, when you are finished building the order, place it:
+
+```ruby
+order = Printfection::Order.retrieve(1)
+order.place
+  #=> true
+```
+
+Or cancel it:
+
+```ruby
+order = Printfection::Order.retrieve(1)
+order.cancel
+  #=> true
+```
+
+
+### Retrieving an item
+
+```ruby
+item = Printfection::Item.retrieve(1)
+  #=> #<Printfection::Item id: 1 ...>
+
+item.name #=> "My Awesome T-Shirt"
+item.color #=> "Green"
+item.product.name #=> "American Apparel 50/50 T-Shirt"
+
+item.campaigns
+  #=> [#<Printfection::Campaign id: 1 ...>, #<Printfection::Campaign id: 2 ...>]
+
+item.sizes
+  #=> [#<Printfection::Size id: 1 ...>, #<Printfection::Size id: 2 ...>]
+
+item.assets
+  #=> [#<Printfection::Asset id: 1 ...>, #<Printfection::Asset id: 2 ...>]
+
+```
+
+### Listing all items
+
+```ruby
+items = Printfection::Items.all
+  #=> [#<Printfection::Item id: 1 ...>, #<Printfection::Item id: 2 ...>]
+```
+
+### Retrieving a campaign
+
+```ruby
+campaign = Printfection::Campaign.retrieve(1)
+  #=> #<Printfection::Campaign id: 1 ...>
+
+campaign.name #=> "My Awesome T-Shirt"
+campaign.type #=> "giveaway"
+campaign.name #=> "My Awesome Giveaway Campaign"
+campaign.active #=> true
+
+```
+
+### Listing all campaigns
+
+```ruby
+campaigns = Printfection::Campaign.all
+  #=> [#<Printfection::Campaign id: 1 ...>, #<Printfection::Campaign id: 2 ...>]
+```
+
+Printfection objects expose all JSON data from the API responses as accessor methods. The full API documentation can be [found here](http://printfection.github.io/API-Documentation).
+
+For additional examples, check out out the [examples directory](examples).
+
+## Errors
+
+Our API bindings can raise exceptions for many reasons, such as a trying to place an incomplete order, invalid parameters, authentication errors, and network unavailability.
+
+Most API errors are captured and raised as a `Printfection::Error`. This makes it easy to gracefully handle exceptions.
+
+```ruby
+begin
+  order = Printfection::Order.create(campaign_id: 1)
+  # This order does not have any line items and
+  # does not have a shipping address,
+  # so trying to place this order will raise.
+  order.place
+rescue Printfection::Error => e
+  # Something went wrong placing this order.
+  puts e.message
+rescue StandardError => e
+  # Something else went wrong.
+  puts e.message
+end
+```
+
+## License
+
+[MIT](LICENCE.txt)
+
+## Issues & Support
+
+[casey.ohara@printfection.com](mailto:casey.ohara@printfection.com)
+
+## Contributing
+
+1. Fork it ( https://github.com/printfection/printfection-ruby/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+
+task :test do
+  sh "rspec spec"
+end
+
+task :default => :test
+

data/lib/printfection/actions.rb

@@ -0,0 +1,40 @@
+module Printfection
+  module Actions
+
+    module Retrieve
+      def retrieve(id)
+        new Printfection.get Util.join_uri(self.uri, id)
+      end
+    end
+
+    module List
+      def all(params={})
+        Printfection.get(self.uri, params).map do |response|
+          new response
+        end
+      end
+    end
+
+    module Create
+      def create(params)
+        new Printfection.post self.uri, params
+      end
+    end
+
+    module Update
+      def save
+        Printfection.patch self.uri, changes
+        true
+      end
+    end
+
+    module Delete
+      def delete
+        Printfection.delete self.uri
+        true
+      end
+    end
+
+  end
+end
+

data/lib/printfection/address.rb

@@ -0,0 +1,15 @@
+module Printfection
+  class Address < Resource
+    property :name
+    property :address
+    property :address2
+    property :company
+    property :city
+    property :state
+    property :zip_code, from: :zip
+    property :country
+    property :email
+    property :phone
+  end
+end
+

data/lib/printfection/api.rb

@@ -0,0 +1,87 @@
+module Printfection
+  module API
+    ENDPOINT = "api.printfection.com/v2/"
+
+    attr_accessor :api_token, :debug_mode
+
+    def get(uri="/", params={})
+      request :get, uri, params
+    end
+
+    def post(uri, data={})
+      request :post, uri, data
+    end
+
+    def patch(uri, data={})
+      request :patch, uri, data
+    end
+
+    def delete(uri)
+      request :delete, uri
+    end
+
+    def request(verb, uri, params={})
+      perform_request do
+        uri = Util.join_uri(ENDPOINT, uri)
+        url = "https://#{api_token}:@#{uri}"
+
+        response = case verb
+        when :get;    RestClient.get url, :params => params, :accept => :json
+        when :post;   RestClient.post url, params.to_json, :accept => :json, :content_type => :json
+        when :patch;  RestClient.patch url, params.to_json, :accept => :json, :content_type => :json
+        when :delete; RestClient.delete url
+        end
+
+        json = JSON.parse(response.body)
+
+        if json["object"] == "list" and json.has_key? "data"
+          json["data"]
+        else
+          json
+        end
+      end
+    end
+
+    private
+
+    def perform_request(&block)
+      return yield if debug_mode
+
+      begin
+        yield
+
+        # At this point, some exception has been raised either
+        # during the request or parsing the response.
+        #
+        # We determine the type of error, and re-raise
+        # our own error from the message in the response body.
+      rescue RestClient::Exception => e
+        # We likely got a http status code outside the 200-399 range.
+        # If this is a GET or DELETE request, it is likely the resource is not owned by the client.
+        # If this is a POST, PUT, or PATCH, the data might be invalid.
+
+        # Handle 400, 401, and 404 errors.
+        # 400 Bad Request  - Invalid or missing request parameters.
+        # 401 Unauthorized - Invalid API key provided.
+        # 404 Not Found    - The requested item doesn't exist or the client doesn't own it.
+        if [400, 401, 404].include?(e.http_code)
+          raise Error, JSON.parse(e.http_body)["message"]
+        end
+
+        # Handle any other http error (i.e. 5xx+), or other RestClient exceptions.
+        # Re-raise a generic error.
+        raise Error, "Something went wrong with the request. Please try again."
+      rescue JSON::ParserError => e
+        # We received the data fine, but we're unable to parse it.
+        # Re-raise a generic error.
+        raise Error, "Something went wrong parsing the response. Please try again."
+      rescue StandardError => e
+        # Something else went wrong.
+        # Re-raise a generic error.
+        raise Error, "Something went wrong. Please try again."
+      end
+    end
+
+  end
+end
+

data/lib/printfection/asset.rb

@@ -0,0 +1,11 @@
+module Printfection
+  class Asset < Resource
+    property :id, transform_with: Transforms::Integer
+    property :type
+    property :name
+    property :perspective
+    property :url
+    property :notes
+  end
+end
+

data/lib/printfection/campaign.rb

@@ -0,0 +1,20 @@
+module Printfection
+  class Campaign < Resource
+    include Hashie::Extensions::Coercion
+    extend Actions::Retrieve
+    extend Actions::List
+
+    property :id, transform_with: Transforms::Integer
+    property :name
+    property :type
+    property :active
+    property :archived
+    property :url
+    property :created_at, transform_with: Transforms::Date
+
+    def self.uri
+      "/campaigns"
+    end
+  end
+end
+

data/lib/printfection/error.rb

@@ -0,0 +1,8 @@
+module Printfection
+  class Error < StandardError
+  end
+
+  class RequestError < Error
+  end
+end
+

data/lib/printfection/item.rb

@@ -0,0 +1,29 @@
+module Printfection
+  class Item < Resource
+    extend Actions::Retrieve
+    extend Actions::List
+
+    property :id, transform_with: Transforms::Integer
+    property :type
+    property :name
+    property :color
+    property :created_at, transform_with: Transforms::Date
+
+    property :product
+    coerce_key :product, Product
+
+    property :campaigns
+    coerce_key :campaigns, Array[Campaign]
+
+    property :sizes
+    coerce_key :sizes, Array[Size]
+
+    property :assets
+    coerce_key :assets, Array[Asset]
+
+    def self.uri
+      "/items"
+    end
+  end
+end
+

data/lib/printfection/line_item.rb

@@ -0,0 +1,21 @@
+module Printfection
+  class LineItem < Resource
+    extend Actions::Retrieve
+    extend Actions::Create
+    include Actions::Update
+    include Actions::Delete
+
+    property :id,         transform_with: Transforms::Integer
+    property :order_id,   transform_with: Transforms::Integer
+    property :item_id,    transform_with: Transforms::Integer
+    property :size_id,    transform_with: Transforms::Integer
+    property :quantity,   transform_with: Transforms::Integer
+    property :created_at, transform_with: Transforms::Date
+
+    def self.uri
+      "/lineitems"
+    end
+
+  end
+end
+

data/lib/printfection/manifest.rb

@@ -0,0 +1,22 @@
+module Printfection
+  class Manifest < Resource
+    property :subtotal,     transform_with: Transforms::Float
+    property :tax,          transform_with: Transforms::Float
+    property :shipping,     transform_with: Transforms::Float
+    property :fulfillment,  transform_with: Transforms::Float
+    property :total,        transform_with: Transforms::Float
+    property :created_at,   transform_with: Transforms::Date
+    property :received_at,  transform_with: Transforms::Date
+    property :approved_at,  transform_with: Transforms::Date
+    property :processed_at, transform_with: Transforms::Date
+    property :shipped_at,   transform_with: Transforms::Date
+    property :completed_at, transform_with: Transforms::Date
+
+    property :line_items, from: :lineitems
+    coerce_key :line_items, Array[LineItem]
+
+    property :shipments
+    coerce_key :shipments, Array[Hashie::Mash]
+  end
+end
+

data/lib/printfection/order.rb

@@ -0,0 +1,99 @@
+module Printfection
+  class Order < Resource
+    extend Actions::Retrieve
+    extend Actions::List
+    extend Actions::Create
+    include Actions::Update
+    include Actions::Delete
+
+    property :id,          transform_with: Transforms::Integer
+    property :campaign_id, transform_with: Transforms::Integer
+    property :created_at,  transform_with: Transforms::Date
+    property :status,      transform_with: lambda { |v| v.downcase }
+    property :code
+    property :url
+    property :gift
+    property :gift_message
+
+    property :line_items, from: :lineitems
+    coerce_key :line_items, Array[LineItem]
+
+    property :ship_to
+    coerce_key :ship_to, Address
+
+    property :manifest
+    coerce_key :manifest, Manifest
+
+    def self.uri
+      "/orders"
+    end
+
+    def line_items
+      Relation.new(
+        parent:   self,
+        children: self[:line_items],
+        klass:    LineItem,
+        path:     '/lineitems',
+        keys:     {:id => :order_id},
+        actions:  [Actions::Retrieve, Actions::Create]
+      )
+    end
+
+    def campaign
+      Campaign.retrieve(campaign_id)
+    end
+
+    def place
+      Printfection.post Util.join_uri(uri, "/place")
+    end
+
+    def cancel
+      delete
+    end
+
+    STATUS_CODES = {
+      "unknown"   => -2,
+      "cancelled" => -1,
+      "open"      => 0,
+      "received"  => 1,
+      "approved"  => 2,
+      "processed" => 3,
+      "shipped"   => 4,
+      "completed" => 5
+    }
+
+    def status_code
+      STATUS_CODES[status]
+    end
+
+    def open?
+      status_code == 0
+    end
+
+    def cancelled?
+      status_code == -1
+    end
+
+    def received?
+      status_code >= 1
+    end
+
+    def approved?
+      status_code >= 2
+    end
+
+    def processed?
+      status_code >= 3
+    end
+
+    def shipped?
+      status_code >= 4
+    end
+
+    def completed?
+      status_code == 5
+    end
+
+  end
+end
+

data/lib/printfection/product.rb

@@ -0,0 +1,7 @@
+module Printfection
+  class Product < Resource
+    property :id, transform_with: Transforms::Integer
+    property :name
+  end
+end
+