sendle-api 0.0.2 → 0.0.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f736e0805af433eab79799321a145b9bcd88b735
-  data.tar.gz: 2e2581b4fe3581e53c107555bafe975580b51f2c
+  metadata.gz: 68b93ccc7a2f1762a621462360bfd3efaa0b9a1e
+  data.tar.gz: eac48906b5c093d3fe83547bebaa9ddd1c3585c4
 SHA512:
-  metadata.gz: 34253eefcf20f679aea3db0dd21f8fa775057174a4ba4f8611a9f36faf0483a64f7334c5209a3ac593f48f73a632fb47bc1a2cd15aaec7e3fb95b8c11478b082
-  data.tar.gz: 3fac7d3704b385c72621ecec7e15e1dc3f2960ecddadaa4e7f26be568fc9645e76462660e1eeb6e062daf383c10e88e7253f74ba4281eb9e6dbfe8f08b75b143
+  metadata.gz: 6d63dfb209cb35f600b6d3f30a4e2ead269245a9a0681a16ab69fbfeb6e062491313e536b5b48be5b9e296881aa496638801fadf6fe40994cdefa22a2227c861
+  data.tar.gz: 5ec6cfacd67a5494cda6335786500ca45aa7ba13f0a6a9118e3093283f0e9abf01b39a6685af28904ecd8edd74b191489e11b6da9ab06febc75ad61ac546519a

data/Changelog.md

@@ -0,0 +1,5 @@
+# Sendle::Api Changes
+
+## 0.0.11
+
+* Initial release!

data/README.md

@@ -1,6 +1,6 @@
 # Sendle::Api
 
-TODO: Write a gem description
+The Sendle API Ruby bindings provide a small SDK for convenient access to the Sendle API from applications written with the Ruby language.
 
 ## Installation
 
@@ -20,7 +20,101 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Before you can use the Sendle API, you need to sign up for a Sendle account. Once you have signed up, you need to send an email to Sendle support requesting access to their API. When access has been granted, you will have access to your sendle_id and api_key, both which are required to access the api.
+
+If you are accessing the Sendle API in sandbox mode, you need to repeat the above process on Sendle's sandbox servers.
+
+### Configuration
+
+Before you can start using the library, you need to configure your api credentials. The instructions below assume you are using this library from a Rails application.
+
+Create a file called 'sendle.rb' inside your config/initializers directory with the following content:
+```
+Sendle::Api.api_key = Rails.application.secrets.sendle_api_key 
+Sendle::Api.sendle_id = Rails.application.secrets.sendle_id
+Sendle::Api.sandbox = true #Only if you are accessing the Sendle sandbox servers, otherwise take out this line.
+```
+
+### Making a Request
+
+Sendle's API documentation can be found here: http://sendle.github.io/sendle-api-doc.
+
+#### Pinging the API
+```
+Sendle::Api::Ping.execute
+```
+
+Returns an instance of Sendle::Api::Responses::Pong upon a successful response from the API. 
+
+#### Getting a Delivery Quote
+```
+params = { pickup_suburb: 'woolloomooloo',
+           pickup_postcode: '2011',
+           delivery_suburb: 'eastgardens',
+           delivery_postcode: '2036',
+           kilogram_weight: '1'
+         }
+response = Sendle::Api::Quote.execute(params)
+
+puts response.json #a hash 
+```
+
+Returns an instance of Sendle::Api::Responses::Json upon a successful response. 
+
+#### Creating an Order
+```
+params = {  pickup_date: "2016-05-05",
+            description: "Kryptonite",
+            kilogram_weight: 1,
+            cubic_metre_volume: 0.01,
+            customer_reference: "SupBdayPressie",
+            sender: {
+              contact: {
+                name: "Lex Luthor",
+                phone: "0412 345 678"
+              },
+              address: {
+                address_line1: "123 Gotham Ln",
+                suburb: "Sydney",
+                state_name: "NSW",
+                postcode: "2000",
+                country: "Australia"
+              },
+              instructions: "Knock loudly"
+            },
+            receiver: {
+              contact: {
+                name: "Clark Kent",
+                email: "clarkissuper@dailyplanet.xyz"
+              },
+              address: {
+                address_line1: "80 Wentworth Park Road",
+                suburb: "Glebe",
+                state_name: "NSW",
+                postcode: "2037",
+                country: "Australia"
+              },
+              instructions: "Give directly to Clark"
+            }
+          }
+response = Sendle::Api::Order.create(params) #response is an instance of Sendle::Api::Responses::Json
+```
+
+#### Viewing an Order
+```
+#response is an instance of Sendle::Api::Responses::Json
+response = Sendle::Api::Order.show("d9a5f8be-a245-4629-bfb5-e019bd9a2a06")
+```
+
+#### Cancelling an Order (only orders with is_cancellable attribute set to true can be cancelled)
+```
+#response is an instance of Sendle::Api::Responses::Json
+response = Sendle::Api::Order.destroy("d9a5f8be-a245-4629-bfb5-e019bd9a2a06")
+```
+
+#### Errors
+Any of the methods described above can throw errors. Check the Sendle API docs for a list of errors and how to resolve them. 
+
 
 ## Contributing
 
@@ -35,10 +129,10 @@ TODO: Write usage instructions here
 1. Navigate to root of this project
 2. Run bundle install to install the gems specified in sendle-api.gemspec
 3. Run bundle exec rake spec to run the tests
+4. After changes and ready to release, up the version in lib/sendle/api/version.rb
+5. Then run 'bundle install' on your testing project. Testing project is installing the sendle-api gem using a local path, so we don't need to release the gem to RubyGems.
+6. Once the gem is ready to be release, follow the instructions below.
 
 ### Release
 1. Make sure you have a RubyGems.org account
 2. bundle exec rake release
-
-### Guide 
-Based on this guide: https://quickleft.com/blog/engineering-lunch-series-step-by-step-guide-to-building-your-first-ruby-gem

data/lib/sendle/api.rb

@@ -1,17 +1,60 @@
+# 3rd party libs
 require 'rest-client'
 
+# Version
 require "sendle/api/version"
 
-require 'stripe/api/ping'
+# Constants
+require "sendle/api/constants"
+
+# Utils
+require 'sendle/api/utils'
+
+# Syntax Sugar
+require 'sendle/api/sugars/index'
+require 'sendle/api/sugars/create'
+require 'sendle/api/sugars/show'
+require 'sendle/api/sugars/destroy'
+
+# Api resource actions
+require 'sendle/api/actions/base'
+require 'sendle/api/actions/index'
+require 'sendle/api/actions/create'
+require 'sendle/api/actions/show'
+require 'sendle/api/actions/destroy'
+
+# Factories
+require 'sendle/api/factories/errors'
+
+# Api errors
+require 'sendle/api/errors/missing_api_key'
+require 'sendle/api/errors/missing_sendle_id'
+require 'sendle/api/errors/unauthorized'
+require 'sendle/api/errors/payment_required'
+require 'sendle/api/errors/missing_params'
+require 'sendle/api/errors/invalid_plan'
+require 'sendle/api/errors/unprocessable_entity'
+require 'sendle/api/errors/precondition_failed'
+
+# Api responses
+require 'sendle/api/responses/pong'
+require 'sendle/api/responses/json'
+
+# Api resources
+require 'sendle/api/resource'
+require 'sendle/api/ping'
+require 'sendle/api/quote'
+require 'sendle/api/order'
 
 module Sendle
   module Api
+    @sandbox = false
 
     class << self
-      attr_accessor :api_key, :sendle_id
+      attr_accessor :api_key, :sendle_id, :sandbox
 
       def base_url
-        "https://sandbox.sendle.com/api/"
+        sandbox ? "https://sandbox.sendle.com/api/" : "https://www.sendle.com/api/"
       end
     end
     

data/lib/sendle/api/actions/base.rb

@@ -0,0 +1,51 @@
+module Sendle
+  module Api
+    module Actions
+      module Base
+
+        def request(params)
+          RestClient::Request.execute(params)
+        rescue RestClient::PreconditionFailed, 
+               RestClient::Unauthorized, 
+               RestClient::PaymentRequired, 
+               RestClient::UnprocessableEntity => e 
+          raise Sendle::Api::Factories::Errors.new_error(e)
+        end
+
+        protected 
+
+          def rest_client_params
+            include_credentials? ? common_params_with_credentials : common_params
+          end
+
+          def common_params
+            {
+              headers: json_headers
+            }
+          end
+
+          def common_params_with_credentials
+            common_params.merge(credential_params)
+          end
+
+          def check_for_missing_credentials
+            return unless self.include_credentials?
+            raise Sendle::Api::Errors::MissingSendleId if Sendle::Api.sendle_id.nil?
+            raise Sendle::Api::Errors::MissingApiKey if Sendle::Api.api_key.nil?
+          end
+
+          def json_headers
+            { accept: :json, content_type: :json }
+          end
+
+          def credential_params
+            {
+              user: Sendle::Api.sendle_id,
+              password: Sendle::Api.api_key
+            }
+          end
+
+      end
+    end
+  end
+end

data/lib/sendle/api/actions/create.rb

@@ -0,0 +1,31 @@
+module Sendle
+  module Api
+    module Actions
+      module Create
+
+        def create(params = {})
+          check_for_missing_credentials
+          validate_create_request!(params)
+
+          request_params = rest_client_params
+          request_params[:method] = :post
+          request_params[:url] = url
+          request_params[:payload] = params 
+
+          process_create_response(request(request_params))
+        end
+
+        def self.included(base)
+          base.extend(Sendle::Api::Sugars::Create)
+        end
+
+        protected
+
+          def http_method
+            :post
+          end
+
+      end
+    end
+  end
+end

data/lib/sendle/api/actions/destroy.rb

@@ -0,0 +1,23 @@
+module Sendle
+  module Api
+    module Actions
+      module Destroy
+
+        def destroy(id)
+          raise Sendle::Api::Errors::MissingParams.new(['id']) if nullish?(id) 
+
+          request_params = rest_client_params
+          request_params[:method] = :delete
+          request_params[:url] = url + '/' + id
+
+          process_destroy_response(request(request_params))
+        end
+
+        def self.included(base)
+          base.extend(Sendle::Api::Sugars::Destroy)
+        end
+
+      end
+    end
+  end
+end

data/lib/sendle/api/actions/index.rb

@@ -2,21 +2,23 @@ module Sendle
   module Api
     module Actions
       module Index
-        
-        def index
-          Sendle::Api::Utils::Actions.check_for_missing_credentials
-          RestClient::Request.execute(
-            method: :get,
-            url: self.url,
-            user: Sendle::Api.sendle_id,
-            password: Sendle::Api.api_key,
-            headers: Sendle::Api::Utils::Actions.json_headers
-          )
-          Sendle::Api::Responses::Pong.new
-        rescue RestClient::Unauthorized => e 
-          response = JSON.parse(e.response)
-          raise Sendle::Api::Errors::Unauthorized.new(response['error_description'])
+
+        def index(params = {})
+          check_for_missing_credentials if include_credentials?
+          validate_index_request!(params) 
+
+          request_params = rest_client_params
+          request_params[:method] = :get
+          request_params[:url] = url
+          request_params[:headers][:params] = params unless params.empty?
+
+          process_index_response(request(request_params))
         end
+
+        def self.included(base)
+          base.extend(Sendle::Api::Sugars::Index)
+        end
+
       end
     end
   end

data/lib/sendle/api/actions/show.rb

@@ -0,0 +1,23 @@
+module Sendle
+  module Api
+    module Actions
+      module Show
+
+        def show(id)
+          raise Sendle::Api::Errors::MissingParams.new(['id']) if nullish?(id) 
+
+          request_params = rest_client_params
+          request_params[:method] = :get
+          request_params[:url] = url + '/' + id
+
+          process_show_response(request(request_params))
+        end
+
+        def self.included(base)
+          base.extend(Sendle::Api::Sugars::Show)
+        end
+
+      end
+    end
+  end
+end

data/lib/sendle/api/constants.rb

@@ -0,0 +1,4 @@
+PLAN_EASY = 'easy'
+PLAN_PREMIUM = 'premium'
+PLAN_PRO = 'pro'
+PLANS = [ PLAN_EASY, PLAN_PREMIUM, PLAN_PRO ]

data/lib/sendle/api/errors/invalid_plan.rb

@@ -0,0 +1,16 @@
+module Sendle
+  module Api
+    module Errors
+      class InvalidPlan < StandardError
+        def initialize(plan)
+          @plan = plan
+        end
+
+        def to_s
+          "#{@plan} is not in the list of valid plans: #{PLANS.join(', ')}"
+        end
+
+      end
+    end
+  end
+end

data/lib/sendle/api/errors/missing_params.rb

@@ -0,0 +1,16 @@
+module Sendle
+  module Api
+    module Errors
+      class MissingParams < StandardError
+        def initialize(*params)
+          @missing_params = params
+        end
+
+        def to_s
+          "The following params are required: #{@missing_params.join(', ')}. Please check your request and try again."
+        end
+
+      end
+    end
+  end
+end

data/lib/sendle/api/errors/payment_required.rb

@@ -0,0 +1,9 @@
+module Sendle
+  module Api
+    module Errors
+      class PaymentRequired < StandardError
+
+      end
+    end
+  end
+end

data/lib/sendle/api/errors/precondition_failed.rb

@@ -0,0 +1,9 @@
+module Sendle
+  module Api
+    module Errors
+      class PreconditionFailed < StandardError
+
+      end
+    end
+  end
+end

data/lib/sendle/api/errors/unprocessable_entity.rb

@@ -0,0 +1,19 @@
+module Sendle
+  module Api
+    module Errors
+      class UnprocessableEntity < StandardError
+
+        def initialize(messages)
+          @messages = messages
+        end
+
+        def to_s
+          msg = "Please fix the following errors and try again - "
+          @messages.each { |k, v| msg += "#{k}: #{v.join(', ')}" }
+          msg
+        end
+
+      end
+    end
+  end
+end