postmen 0.1.0 → 1.0.0.pre.alpha.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e0c166c6e9e1ba64fa64b643d122c137684d1405
-  data.tar.gz: e0df26f3ce8ee0d14c662cdcc776d143c59abc7e
+  metadata.gz: ef3279747f60ddf021d56412eed1d833adb77f1c
+  data.tar.gz: e93b892733da84d2b7d3ae556c004baef30bc9f6
 SHA512:
-  metadata.gz: bbe91de55327692811997e3402792f4a3e45520dccd0a91feb81f7d42ffc55a6e01e312570f251965b96194b6ec3297ac9feb55305af629fedfbba346de99c08
-  data.tar.gz: de33322a0d03cfe24e5c96405503eb165c82273912b21032de64348601b4bd0bdd1f267d0cee7e245056e856f913caac61fee4e853d8c21bec6d7c7344780cb5
+  metadata.gz: 721df92fa7baf87693a78098a04cf5f1986f8829ff2f83a752899767fd2aa147ab252f16065b807408108e3872ae6e81c972c024c7231c06ea6c09ec4a02a625
+  data.tar.gz: 9436a466ca9044c098e05e3df986861bbe5f64dd257f944f486341cddc5dfbd791437bc0dee7ffea3df7e234f352fd96f38893dd0380dbd7ced2ab4f7f5867db

data/README.md

@@ -4,6 +4,9 @@
 [![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)
+[![Coverage Status](https://coveralls.io/repos/github/postmen/postmen-sdk-ruby/badge.svg?branch=master)](https://coveralls.io/github/postmen/postmen-sdk-ruby?branch=master)
+[![Documentation status](https://inch-ci.org/github/postmen/postmen-sdk-ruby.svg?branch=master)](https://inch-ci.org/github/postmen/postmen-sdk-ruby)
+
 
 Ruby Gem for Postmen API.
 
@@ -20,7 +23,7 @@ This gem is on early stage of development - There are a lot of features that are
 1. Add the following line to your application's Gemfile
 
     ```
-    gem "postmen", "~> 0.0.1"
+    gem "postmen", "~> 0.1.0"
     ```
 
 2. Run bundler

data/lib/postmen/collection_proxy.rb

@@ -1,26 +1,46 @@
 class Postmen
+  # This is a mixin used by all collections.
+  # For an user perspective, every collection should
+  # behave like a simple array of models.
   module CollectionProxy
     include Enumerable
     extend Forwardable
 
+    # This module holds all class-level methods
     module ClassMethods
+      # Settings hash. Used in model/key methods.
       attr_reader :settings
 
+      # Sets (if argument is provided) or gets the model class name
+      #
+      # @return [Class] Model name, eg. `Label`
       def model(model = nil)
         return settings[:model] unless model
         settings[:model] = model
       end
 
+      # Sets (if argument is provides) or gets the key where the data is being
+      # searched in the API response.
+      #
+      # @see https://docs.postmen.com/#data API documentation
+      # @return [Symbol] key name
       def key(key = nil)
         return settings[:key] unless key
         settings[:key] = key
       end
 
+      # Wraps raw JSON response into an model
+      #
+      # @param response [Hash] parsed JSON response
+      # @return model an instance of
       def get(response)
         model.new(response[:data])
       end
     end
 
+    # Method called on base object when mixin gets included
+    #
+    # @private
     def self.included(base)
       base.extend ClassMethods
       base.instance_variable_set('@settings', {})
@@ -28,6 +48,8 @@ class Postmen
 
     def_delegators :@data, :[], :each
 
+    # Constructor
+    # @param response [Hash] HTTP response, parsed by the Response class
     def initialize(response)
       @data = response[:data][self.class.key].map { |element| self.class.model.new(element) }
     end

data/lib/postmen/connection.rb

@@ -1,11 +1,21 @@
 class Postmen
+  # Connection class is used to perform any HTTP connections,
+  # it also does error handling.
   class Connection
+    # Maximum number of retries
     MAX_REQUESTS = 5
 
     def initialize
       @requests = 0
     end
 
+    # Performs a HTTP GET request.
+    #
+    # @param path [String]
+    # @param options [Hash]
+    # @example
+    #   .get('/labels')
+    #   .get('/labels', { params: { limit: 5 } })
     def get(path, options = {})
       Response.new(raw_get(path, options)).tap(&:parse_response!)
     rescue RateLimitExceeded
@@ -15,10 +25,38 @@ class Postmen
       retry
     end
 
+    # Performs a HTTP POST request.
+    #
+    # @param path [String]
+    # @param options [Hash]
+    # @example
+    #   .post('/labels')
+    #   .post('/labels', { json: { my: { sample: :data } } })
     def post(path, options = {})
       Response.new(raw_post(path, options))
     end
 
+    # Performs a HTTP PUT request.
+    #
+    # @param path [String]
+    # @param options [Hash]
+    # @example
+    #   .put('/shipper-accounts/123/info')
+    #   ..put('/shipper-accounts/123/info', { json: { my: { sample: :data } } })
+    def put(path, options = {})
+      Response.new(raw_put(path, options))
+    end
+    # Performs a HTTP DELETE request
+    #
+    # @param path [String]
+    # @example
+    #   .delete('/shipper-accounts/11111')
+    def delete(path)
+      HTTP
+        .headers(headers)
+        .delete(get_full_url(path))
+    end
+
     private
 
     def raw_get(path, options)
@@ -33,6 +71,12 @@ class Postmen
         .post(get_full_url(path), options)
     end
 
+    def raw_put(path, options)
+      HTTP
+        .headers(headers)
+        .put(get_full_url(path), options)
+    end
+
     def get_full_url(path)
       [Postmen.endpoint, path].join
     end

data/lib/postmen/label.rb

@@ -1,4 +1,7 @@
 class Postmen
+  # Label object
+  #
+  # @see https://docs.postmen.com/api.html#labels API documentation
   class Label < Dry::Struct
     attribute :id, Types::UUID
     attribute :status, Types::String
@@ -6,14 +9,26 @@ class Postmen
     attribute :files, Types::Strict::Nil | Types::Array.member(Types::Hash)
     attribute :rate, Types::Strict::Nil | Types::Hash
 
+    # Returns all labels
+    #
+    # @see LabelCollection#all
+    # @return [LabelCollection] Collection of Labels
     def self.all(options = {})
       LabelCollection.all(options)
     end
 
+    # Fetches single label
+    #
+    # @see LabelCollection#find
+    # @return [Label]
     def self.find(id)
       LabelCollection.find(id)
     end
 
+    # Creates an instance of Label
+    #
+    # @see LabelCollection#create
+    # @return [Label]
     def self.create(params)
       LabelCollection.create(params)
     end

data/lib/postmen/label_collection.rb

@@ -1,18 +1,37 @@
 class Postmen
+  # This class wraps the array of Label models
   class LabelCollection
     include CollectionProxy
 
     model Label
     key :labels
 
+    # Fetch all labels.
+    #
+    # @param options [Hash] Options for the query.
+    # @see https://docs.postmen.com/api.html#labels-list-all-labels API documentation
+    # @example
+    #   .all # Returns all labels, default query.
+    #   .all(status: :cancelled) # Returns only cancelled labels
     def self.all(options = {})
       new(Connection.new.get('/labels', LabelQuery.new(options).to_query).parsed_response)
     end
 
+    # Fetch single label
+    #
+    # @param id [UUID] Label UUID
+    # @see https://docs.postmen.com/api.html#labels-retrieve-a-label API documentation
+    # @return [Label]
+    # @raise ResourceNotFound if label with given id was not fount
     def self.find(id)
       get(Connection.new.get("/labels/#{id}").parsed_response)
     end
 
+    # Creates a label
+    #
+    # @param params [Hash] Label params
+    # @see https://docs.postmen.com/api.html#labels-create-a-label API documentation
+    # @return [Label]
     def self.create(params)
       Label.new(Connection.new.post('/labels', CreateLabelQuery.new(params).to_query).parsed_response[:data])
     end

data/lib/postmen/manifest.rb

@@ -0,0 +1,38 @@
+class Postmen
+  # A manifest object object
+  #
+  # @see https://docs.postmen.com/api.html#a-manifest-object API Documentation
+  class Manifest < Dry::Struct
+    attribute :id, Types::UUID
+    attribute :status, Types::ManifestStatuses
+    attribute :shipper_account, Types::Reference
+    attribute :labels, Types::Array # TODO: implement manifesting label type
+    attribute :files, Types::Hash # TODO: Implement Files Type
+    attribute :created_at, Types::DateTime
+    attribute :updated_at, Types::DateTime
+
+    # Returns all manifests
+    #
+    # @see ManifestCollection#all
+    # @return [ManifestCollection] Collection of Manifests
+    def self.all(options = {})
+      ManifestCollection.all(options)
+    end
+
+    # Fetches single manifest
+    #
+    # @see ManifestCollection#find
+    # @return [Manifest]
+    def self.find(id)
+      ManifestCollection.find(id)
+    end
+
+    # Creates an instance of manifest
+    #
+    # @see ManifestCollection#create
+    # @return [Manifest]
+    def self.create(params)
+      ManifestCollection.create(params)
+    end
+  end
+end

data/lib/postmen/manifest_collection.rb

@@ -0,0 +1,39 @@
+class Postmen
+  # This class wraps the array of Manifest models
+  class ManifestCollection
+    include CollectionProxy
+
+    model Manifest
+    key :manifests
+
+    # Fetch all manifests.
+    #
+    # @param options [Hash] Options for the query.
+    # @see https://docs.postmen.com/api.html#manifests-list-all-manifests API Documentation
+    # @example
+    #   .all # Returns all manisfests, default query.
+    #   .all(status: :failed) # Returns only failed manifests
+    def self.all(options = {})
+      new(Connection.new.get('/manifests', ManifestQuery.new(options).to_query).parsed_response)
+    end
+
+    # Fetch single manifest
+    #
+    # @param id [UUID] Manifest UUID
+    # @see https://docs.postmen.com/api.html#manifests-retrieve-a-manifest API documentation
+    # @return [Manifest]
+    # @raise ResourceNotFound if Manifest with given id was not found
+    def self.find(id)
+      get(Connection.new.get("/manifests/#{id}").parsed_response)
+    end
+
+    # Creates a Manifest
+    #
+    # @param params [Hash] Manifest params
+    # @see https://docs.postmen.com/api.html#manifests-create-a-manifest API documentation
+    # @return [Rate]
+    def self.create(params)
+      Manifest.new(Connection.new.post('/manifests', CreateManifestQuery.new(params).to_query).parsed_response[:data])
+    end
+  end
+end

data/lib/postmen/parcel.rb

@@ -0,0 +1,12 @@
+class Postmen
+  # Parcel object
+  #
+  # @see https://docs.postmen.com/api.html#parcel API Documentation
+  class Parcel < Dry::Struct
+    attribute :description, Types::String
+    attribute :box_type, Types::String
+    attribute :weight, Types::Weight
+    attribute :dimension, Types::Dimension
+    attribute :items, Types::Array.member(Types::Item)
+  end
+end

data/lib/postmen/query/create_label_query.rb

@@ -1,10 +1,13 @@
 class Postmen
+  # This class holds all the logic behind preparing query for
+  # creating a Label. It does type convertion, removes empty values and so on.
+  # @see LabelCollection#create Usage
   class CreateLabelQuery < Dry::Struct
     constructor_type :strict_with_defaults
 
     attribute :service_type, Types::String
     attribute :shipper_account, Types::Reference
-    attribute :shipment, Types::Shipment
+    attribute :shipment, Shipment
     attribute :async, Types::Bool.optional.default(nil)
     attribute :return_shipment, Types::Bool.optional.default(nil)
     attribute :paper_size, Types::PaperSize.optional.default(nil)
@@ -15,6 +18,8 @@ class Postmen
     attribute :billing, Types::Billing.optional.default(nil)
     attribute :customs, Types::Customs.optional.default(nil)
 
+    # Converts query object to hash
+    # @return [Hash]
     def to_query
       {
         json: query

data/lib/postmen/query/create_manifest_query.rb

@@ -0,0 +1,23 @@
+class Postmen
+  # This class holds all the logic behind preparing query for
+  # creating a Manifest. It does type convertion, removes empty values and so on.
+  class CreateManifestQuery < Dry::Struct
+    constructor_type :strict_with_defaults
+
+    attribute :shipper_account, Types::Reference
+
+    # Converts query object to hash
+    # @return [Hash]
+    def to_query
+      {
+        json: query
+      }
+    end
+
+    private
+
+    def query
+      to_hash.reject { |_k, v| v.nil? }
+    end
+  end
+end

data/lib/postmen/query/create_rate_query.rb

@@ -0,0 +1,27 @@
+class Postmen
+  # This class holds all the logic behind preparing query for
+  # creating a Rate. It does type convertion, removes empty values and so on.
+  class CreateRateQuery < Dry::Struct
+    constructor_type :strict_with_defaults
+
+    # async	boolean	enable async mode or not (set to false if not provided)
+    # is_document	boolean	If the shipment is document type. (set to false if not provided)
+
+    attribute :shipment, Shipment
+    attribute :shipper_accounts, Types::Array.member(Types::Reference)
+
+    # Converts query object to hash
+    # @return [Hash]
+    def to_query
+      {
+        json: query
+      }
+    end
+
+    private
+
+    def query
+      to_hash.reject { |_k, v| v.nil? }
+    end
+  end
+end

data/lib/postmen/query/create_shipper_account_query.rb

@@ -0,0 +1,22 @@
+class Postmen
+  # This class holds all the logic behind preparing query for
+  # creating a ShipperAccount. It does type convertion, removes empty values and so on.
+  # @see ShipperAccountCollection#create Usage
+  class CreateShipperAccountQuery < Dry::Struct
+    constructor_type :schema
+
+    attribute :slug, Types::String
+    attribute :description, Types::String
+    attribute :address, Types::Address
+    attribute :timezone, Types::Timezone
+    attribute :credentials, Types::Hash
+
+    # Converts query object to hash
+    # @return [Hash]
+    def to_query
+      {
+        params: query
+      }
+    end
+  end
+end

data/lib/postmen/query/label_query.rb

@@ -1,17 +1,23 @@
 class Postmen
+  # This class holds all the logic behind querying for a single Label.
+  # @see LabelCollection.find Usage
   class LabelQuery < Dry::Struct
+    # Expected format for dates
+    # example value: 2017-02-08T10:17:04+01:00
     DATE_FORMAT = '%FT%T%:z'.freeze
 
     constructor_type :schema
 
     attribute :shipper_account_id, Types::String.optional
-    attribute :status, Types::Strict::Nil | Types::Statuses
+    attribute :status, Types::Strict::Nil | Types::LabelStatuses
     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
 
+    # Converts query object to hash
+    # @return [Hash]
     def to_query
       {
         params: query

data/lib/postmen/query/manifest_query.rb

@@ -0,0 +1,50 @@
+# shipper_account_id	string	Shipper account ID
+# status	string	Manifest status Accepts: manifesting,manifested,failed.
+# limit	string	Number of records per page
+# created_at_min	string	Start date and time of the record created (default: 24hrs ago)
+# created_at_max	string	End date and time of the record created (default: NOW())
+# next_token	string	Next token
+
+class Postmen
+  # This class holds all the logic behind querying for a single Manifest.
+  # @see ManifestCollection.find Usage
+  class ManifestQuery < Dry::Struct
+    # Expected format for dates
+    # example value: 2017-02-08T10:17:04+01:00
+    DATE_FORMAT = '%FT%T%:z'.freeze
+
+    constructor_type :schema
+
+    attribute :shipper_account_id, Types::String.optional
+    attribute :status, Types::Strict::Nil | Types::ManifestStatuses
+    attribute :limit, Types::String.optional
+    attribute :created_at_min, Types::DateTime.maybe
+    attribute :created_at_max, Types::DateTime.maybe
+    attribute :next_token, Types::String.optional
+
+    # Converts query object to hash
+    # @return [Hash]
+    def to_query
+      {
+        params: query
+      }
+    end
+
+    private
+
+    def format_date(date)
+      date.fmap { |d| d.strftime(DATE_FORMAT) }.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),
+        next_token: next_token
+      }.reject { |_k, v| v.nil? }
+    end
+  end
+end

data/lib/postmen/query/rate_query.rb

@@ -0,0 +1,41 @@
+class Postmen
+  # This class holds all the logic behind querying for a single Rate.
+  # @see RateCollection.find Usage
+  class RateQuery < Dry::Struct
+    # Expected format for dates
+    # example value: 2017-02-08T10:17:04+01:00
+    DATE_FORMAT = '%FT%T%:z'.freeze
+
+    constructor_type :schema
+
+    attribute :status, Types::Strict::Nil | Types::RateStatuses
+    attribute :limit, Types::String.optional
+    attribute :created_at_min, Types::DateTime.maybe
+    attribute :created_at_max, Types::DateTime.maybe
+    attribute :next_token, Types::String.optional
+
+    # Converts query object to hash
+    # @return [Hash]
+    def to_query
+      {
+        params: query
+      }
+    end
+
+    private
+
+    def format_date(date)
+      date.fmap { |d| d.strftime(DATE_FORMAT) }.value
+    end
+
+    def query
+      {
+        status: status,
+        limit: limit,
+        created_at_min: format_date(created_at_min),
+        created_at_max: format_date(created_at_max),
+        next_token: next_token
+      }.reject { |_k, v| v.nil? }
+    end
+  end
+end

data/lib/postmen/query/shipper_account_query.rb

@@ -0,0 +1,29 @@
+class Postmen
+  # This class holds all the logic behind querying for a single ShipperAccount.
+  # @see ShipperAccountCollection.find Usage
+  class ShipperAccountQuery < Dry::Struct
+    constructor_type :schema
+
+    attribute :slug, Types::String
+    attribute :limit, Types::Int
+    attribute :next_token, Types::String
+
+    # Converts query object to hash
+    # @return [Hash]
+    def to_query
+      {
+        params: query
+      }
+    end
+
+    private
+
+    def query
+      {
+        slug: slug,
+        limit: limit,
+        next_token: next_token
+      }.reject { |_k, v| v.nil? }
+    end
+  end
+end

data/lib/postmen/query/shipper_account_update_credentials_query.rb

@@ -0,0 +1,20 @@
+class Postmen
+  # This class holds all the logic behind
+  # updating credentials for a ShipperAccount details
+  # @see ShipperAccount.update_credentials Usage
+  class ShipperAccountUpdateCredentialsQuery < Dry::Types::Hash
+    # Converts query object to hash
+    # @return [Hash]
+    def to_query
+      {
+        json: query
+      }
+    end
+
+    private
+
+    def query
+      primitive.reject { |_k, v| v.nil? }
+    end
+  end
+end

data/lib/postmen/query/shipper_account_update_query.rb

@@ -0,0 +1,30 @@
+class Postmen
+  # This class holds all the logic behind updating a ShipperAccount details
+  # @see ShipperAccount.update Usage
+  class ShipperAccountUpdateQuery < Dry::Struct
+    constructor_type :schema
+
+    attribute :subject, ShipperAccount
+    attribute :description, Types::String
+    attribute :timezone, Types::Timezone
+    attribute :address, Types::Address
+
+    # Converts query object to hash
+    # @return [Hash]
+    def to_query
+      {
+        json: query
+      }
+    end
+
+    private
+
+    def query
+      {
+        description: description || subject.description,
+        timezone: timezone || subject.timezone,
+        address: (address || subject.address).to_h
+      }.reject { |_k, v| v.nil? }
+    end
+  end
+end

data/lib/postmen/rate.rb

@@ -0,0 +1,35 @@
+class Postmen
+  # Rate object
+  # It encapsulates Rate record objects
+  # @see RateObject
+  # @see https://docs.postmen.com/api.html#rates API documentation
+  class Rate < Dry::Struct
+    attribute :id, Types::UUID
+    attribute :status, Types::RateStatuses
+    attribute :rates, Types::Array.member(RateObject)
+
+    # Returns all rates
+    #
+    # @see RateCollection#all
+    # @return [RateCollection] Collection of Rates
+    def self.all(options = {})
+      RateCollection.all(options)
+    end
+
+    # Fetches single rate
+    #
+    # @see RateCollection#find
+    # @return [Rate]
+    def self.find(id)
+      RateCollection.find(id)
+    end
+
+    # Creates an instance of Rate
+    #
+    # @see RateCollection#create
+    # @return [Rate]
+    def self.create(params)
+      RateCollection.create(params)
+    end
+  end
+end