postmen 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 69b96807bb918ab129964560c96ecc008d9995b2
-  data.tar.gz: 7fc927aab17ea0aac6752862fe133bcfbb5de830
+  metadata.gz: e0c166c6e9e1ba64fa64b643d122c137684d1405
+  data.tar.gz: e0df26f3ce8ee0d14c662cdcc776d143c59abc7e
 SHA512:
-  metadata.gz: d4422ea111c232423449c6a91eeb32482ccf4011724688eacd92da33c9e4b15ef5dff443e41cbb0362299749057c57978449f83a5d84af9c81e0108886337c66
-  data.tar.gz: 7cc0b50e65fd84c532957798f6aef459906f4f0d7cbb12dc6c744321bcbb4cec20e4ac9c9fcb699fc8667d4c3a971c6e8de37320c7f478f3cc966a23e23f567f
+  metadata.gz: bbe91de55327692811997e3402792f4a3e45520dccd0a91feb81f7d42ffc55a6e01e312570f251965b96194b6ec3297ac9feb55305af629fedfbba346de99c08
+  data.tar.gz: de33322a0d03cfe24e5c96405503eb165c82273912b21032de64348601b4bd0bdd1f267d0cee7e245056e856f913caac61fee4e853d8c21bec6d7c7344780cb5

data/README.md

@@ -1,14 +1,18 @@
 ## postmen-ruby
 
+[![Build Status](https://travis-ci.org/postmen/postmen-sdk-ruby.svg?branch=master)](https://travis-ci.org/postmen/postmen-sdk-ruby)
+[![Code Climate](https://codeclimate.com/github/postmen/postmen-sdk-ruby/badges/gpa.svg)](https://codeclimate.com/github/postmen/postmen-sdk-ruby)
+[![Gem Version](https://badge.fury.io/rb/postmen.svg)](https://badge.fury.io/rb/postmen)
+[![Dependency Status](https://gemnasium.com/badges/github.com/postmen/postmen-sdk-ruby.svg)](https://gemnasium.com/github.com/postmen/postmen-sdk-ruby)
+
 Ruby Gem for Postmen API.
 
 This extension helps developers to integrate with Postmen easily.
 
-## About Postmen
-
+## Early development stage
 
+This gem is on early stage of development - There are a lot of features that are not covered yet, you may also expect heavy changes in the public API, before we hit version `1.0.0` (see the Milestones section)
 
-### Changes
 
 
 ## Installation
@@ -27,9 +31,61 @@ This extension helps developers to integrate with Postmen easily.
 
 ## Configuration
 
+```ruby
+
+Postmen.configure do |config|
+  config.region = 'sandbox' # set 'sandbox' or 'production. Required
+  config.api_key = 'YOUR API KEY' # Required
+  config.endpoint = 'http://my-custom-endpoint.example.com' # Optionally set custom endpoint url.
+end
+
+```
 
 ## Usage
 
+```ruby
+require 'postmen'
+
+# Configure postmen first, see Configuration section
+
+### Fetch all labels:
+
+Postmen::Label.all # Returns an instance of Postmen::LabelCollection
+
+# optionally you can pass additional params to the query:
+
+Postmen::Label.all(shipper_account_id: '1111')
+Postmen::Label.all(status: 'created')
+# For more options, please see the documentation: https://docs.postmen.com/api.html#labels-list-all-labels
+
+### Fetch single label
+
+Postmen::Label.find('1111') # Returns an instance of Postmen::Label
+```
+
+### Label
+
+An instance of `Postmen::Label` responds to following methods:
+
+`id`,
+`status`,
+`tracking_numbers`
+`files`,
+`rate`
+
+### LabelCollection
+
+`Postmen::LabelCollection` acts as an Array of `Label` instances. You can do things like:
+
+```ruby
+collection = Postmen::Label.all 
+
+collection.first # Returns an instance of Label
+collection.size # Returns number of elements returned
+collection.each{|label| puts label.inspect } # Iterates over labels
+collection.select{|label|  } # Selects labels by given criteria
+```
+and so on.
 
 ## The License (MIT)
 

data/lib/postmen/collection_proxy.rb

@@ -0,0 +1,35 @@
+class Postmen
+  module CollectionProxy
+    include Enumerable
+    extend Forwardable
+
+    module ClassMethods
+      attr_reader :settings
+
+      def model(model = nil)
+        return settings[:model] unless model
+        settings[:model] = model
+      end
+
+      def key(key = nil)
+        return settings[:key] unless key
+        settings[:key] = key
+      end
+
+      def get(response)
+        model.new(response[:data])
+      end
+    end
+
+    def self.included(base)
+      base.extend ClassMethods
+      base.instance_variable_set('@settings', {})
+    end
+
+    def_delegators :@data, :[], :each
+
+    def initialize(response)
+      @data = response[:data][self.class.key].map { |element| self.class.model.new(element) }
+    end
+  end
+end

data/lib/postmen/connection.rb

@@ -0,0 +1,47 @@
+class Postmen
+  class Connection
+    MAX_REQUESTS = 5
+
+    def initialize
+      @requests = 0
+    end
+
+    def get(path, options = {})
+      Response.new(raw_get(path, options)).tap(&:parse_response!)
+    rescue RateLimitExceeded
+      @requests += 1
+      raise if @requests > MAX_REQUESTS
+      sleep(60)
+      retry
+    end
+
+    def post(path, options = {})
+      Response.new(raw_post(path, options))
+    end
+
+    private
+
+    def raw_get(path, options)
+      HTTP
+        .headers(headers)
+        .get(get_full_url(path), options)
+    end
+
+    def raw_post(path, options)
+      HTTP
+        .headers(headers)
+        .post(get_full_url(path), options)
+    end
+
+    def get_full_url(path)
+      [Postmen.endpoint, path].join
+    end
+
+    def headers
+      {
+        "content-type": 'application/json',
+        "postmen-api-key": Postmen.config.api_key
+      }
+    end
+  end
+end

data/lib/postmen/label.rb

@@ -0,0 +1,21 @@
+class Postmen
+  class Label < Dry::Struct
+    attribute :id, Types::UUID
+    attribute :status, Types::String
+    attribute :tracking_numbers, Types::Array.member(Types::String)
+    attribute :files, Types::Strict::Nil | Types::Array.member(Types::Hash)
+    attribute :rate, Types::Strict::Nil | Types::Hash
+
+    def self.all(options = {})
+      LabelCollection.all(options)
+    end
+
+    def self.find(id)
+      LabelCollection.find(id)
+    end
+
+    def self.create(params)
+      LabelCollection.create(params)
+    end
+  end
+end

data/lib/postmen/label_collection.rb

@@ -0,0 +1,20 @@
+class Postmen
+  class LabelCollection
+    include CollectionProxy
+
+    model Label
+    key :labels
+
+    def self.all(options = {})
+      new(Connection.new.get('/labels', LabelQuery.new(options).to_query).parsed_response)
+    end
+
+    def self.find(id)
+      get(Connection.new.get("/labels/#{id}").parsed_response)
+    end
+
+    def self.create(params)
+      Label.new(Connection.new.post('/labels', CreateLabelQuery.new(params).to_query).parsed_response[:data])
+    end
+  end
+end

data/lib/postmen/query/create_label_query.rb

@@ -0,0 +1,30 @@
+class Postmen
+  class CreateLabelQuery < Dry::Struct
+    constructor_type :strict_with_defaults
+
+    attribute :service_type, Types::String
+    attribute :shipper_account, Types::Reference
+    attribute :shipment, Types::Shipment
+    attribute :async, Types::Bool.optional.default(nil)
+    attribute :return_shipment, Types::Bool.optional.default(nil)
+    attribute :paper_size, Types::PaperSize.optional.default(nil)
+    attribute :ship_date, Types::String.optional.default(nil)
+    # attribute :service_options
+    attribute :is_document, Types::Bool.optional.default(nil)
+    attribute :invoice, Types::Invoice.optional.default(nil)
+    attribute :billing, Types::Billing.optional.default(nil)
+    attribute :customs, Types::Customs.optional.default(nil)
+
+    def to_query
+      {
+        json: query
+      }
+    end
+
+    private
+
+    def query
+      to_hash.reject { |_k, v| v.nil? }
+    end
+  end
+end

data/lib/postmen/query/label_query.rb

@@ -0,0 +1,43 @@
+class Postmen
+  class LabelQuery < Dry::Struct
+    DATE_FORMAT = '%FT%T%:z'.freeze
+
+    constructor_type :schema
+
+    attribute :shipper_account_id, Types::String.optional
+    attribute :status, Types::Strict::Nil | Types::Statuses
+    attribute :limit, Types::String.optional
+    attribute :created_at_min, Types::DateTime.maybe
+    attribute :created_at_max, Types::DateTime.maybe
+    attribute :tracking_numbers, Types::String.maybe
+    attribute :next_token, Types::String.optional
+
+    def to_query
+      {
+        params: query
+      }
+    end
+
+    private
+
+    def format_date(date)
+      date.fmap { |d| d.strftime(DATE_FORMAT) }.value
+    end
+
+    def formatted_tracking_numbers
+      tracking_numbers.fmap { |numbers| Array(numbers).join(',') }.value
+    end
+
+    def query
+      {
+        shipper_account_id: shipper_account_id,
+        status: status,
+        limit: limit,
+        created_at_min: format_date(created_at_min),
+        created_at_max: format_date(created_at_max),
+        tracking_numbers: formatted_tracking_numbers,
+        next_token: next_token
+      }.reject { |_k, v| v.nil? }
+    end
+  end
+end

data/lib/postmen/response.rb

@@ -0,0 +1,46 @@
+class Postmen
+  class Response < SimpleDelegator
+    def parse_response!
+      ensure_rate_limit!
+      ensure_resource_found!
+    end
+
+    def meta
+      @meta ||= parsed_response[:meta]
+    end
+
+    def parsed_response
+      @parsed_response ||= JSON.parse(body, symbolize_names: true)
+    end
+
+    def rate_limit_exceeded?
+      code == 429
+    end
+
+    def remaining_api_calls
+      Integer(headers['X-RateLimit-Remaining'])
+    end
+
+    def api_rate_limit
+      Integer(headers['X-RateLimit-Limit'])
+    end
+
+    def api_rate_limit_reset
+      Integer(headers['X-RateLimit-Reset'])
+    end
+
+    def api_rate_limit_reset_at
+      Time.at(api_rate_limit_reset)
+    end
+
+    private
+
+    def ensure_rate_limit!
+      raise RateLimitExceeded, self if rate_limit_exceeded?
+    end
+
+    def ensure_resource_found!
+      raise ResourceNotFound, self if meta[:code] == 4153
+    end
+  end
+end

data/lib/postmen/types.rb

@@ -0,0 +1,37 @@
+Dry::Types.load_extensions(:maybe)
+
+class Postmen
+  module Types
+    include Dry::Types.module
+
+    UUID = Types::Strict::String.constrained(
+      format: /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+    )
+
+    Statuses = Types::String.enum(
+      'creating',
+      'created',
+      'cancelling',
+      'cancelled',
+      'manifesting',
+      'manifested',
+      'failed'
+    )
+
+    Reference = Types::Hash.schema(id: Types::UUID)
+    Shipment = Types::Hash
+    PaperSize = Types::String.enum(
+      '4x4',
+      '4x6',
+      '4x6.75',
+      '4x8',
+      '6x4',
+      'a4',
+      'default'
+    )
+
+    Invoice = Types::Hash
+    Billing = Types::Hash
+    Customs = Types::Hash
+  end
+end

data/lib/postmen/version.rb

@@ -0,0 +1,3 @@
+class Postmen
+  VERSION = '0.1.0'.freeze
+end

data/lib/postmen.rb

@@ -1,9 +1,38 @@
-$:.unshift File.dirname(__FILE__)
+require 'dry-configurable'
+require 'dry-struct'
+require 'http'
+require 'json'
+require 'pathname'
+require 'forwardable'
 
-module Postmen
-  class << self;
-    attr_accessor :api_key
+require 'postmen/version'
+require 'postmen/types'
+require 'postmen/connection'
+require 'postmen/collection_proxy'
+require 'postmen/label'
+require 'postmen/label_collection'
+require 'postmen/response'
+require 'postmen/query/label_query'
+require 'postmen/query/create_label_query'
+
+class Postmen
+  extend Dry::Configurable
+
+  Error = Class.new(StandardError)
+  RateLimitExceeded = Class.new(Error)
+  ConnectionError = Class.new(Error)
+  RequestError = Class.new(Error)
+  ResourceNotFound = Class.new(RequestError)
+
+  setting :api_key
+  setting :region
+  setting :endpoint
+
+  def self.endpoint
+    config.endpoint || "https://#{config.region}-api.postmen.com/v3"
   end
 
-  URL = ENV['POSTMEN_API_ENDPOINT'] || 'https://api.postmen.com'
+  def self.root
+    Pathname.new(File.expand_path(File.join(File.dirname(__FILE__), '../')))
+  end
 end

metadata

@@ -1,57 +1,127 @@
 --- !ruby/object:Gem::Specification
 name: postmen
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - postmen.com
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-12-15 00:00:00.000000000 Z
+date: 2017-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: httpclient
+  name: http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: dry-configurable
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.5.2
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.5.2
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: dry-struct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: dry-monads
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.14.1
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.14.1
+        version: '2.3'
 - !ruby/object:Gem::Dependency
-  name: pry
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ">"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ">"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '10.0'
 description: Developed for easy integration with Postmen
 email:
 - support@postmen.com
@@ -61,6 +131,15 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/postmen.rb
+- lib/postmen/collection_proxy.rb
+- lib/postmen/connection.rb
+- lib/postmen/label.rb
+- lib/postmen/label_collection.rb
+- lib/postmen/query/create_label_query.rb
+- lib/postmen/query/label_query.rb
+- lib/postmen/response.rb
+- lib/postmen/types.rb
+- lib/postmen/version.rb
 homepage: https://www.postmen.com
 licenses:
 - MIT
@@ -73,16 +152,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 1.8.7
+      version: 2.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
-requirements:
-- none
+requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Postmen