postmen 0.1.0 → 1.0.0.pre.alpha.1

data/lib/postmen/rate_collection.rb

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

data/lib/postmen/rate_object.rb

@@ -0,0 +1,19 @@
+class Postmen
+  # Rate record object
+  #
+  # @see https://docs.postmen.com/api.html#rates API documentation
+  class RateObject < Dry::Struct
+    attribute :shipper_account, Types::BriefShipperAccount
+    attribute :service_type, Types::String
+    attribute :service_name, Types::String
+    attribute :charge_weight, Types::Weight
+    attribute :total_charge, Types::Money
+    attribute :pickup_deadline, Types::String
+    attribute :booking_cut_off, Types::Date
+    attribute :delivery_date, Types::String
+    attribute :transit_time, Types::String
+    attribute :detailed_charges, Types::Array.member(Types::DetailedCharges)
+    attribute :info_message, Types::String
+    attribute :error_message, Types::String
+  end
+end

data/lib/postmen/response.rb

@@ -1,44 +1,64 @@
 class Postmen
+  # This class parses the HTTP response and checks if it was successfull.
   class Response < SimpleDelegator
+    # Parses response.
+    # Ensures that rate limit was not exceeded,
+    # and checks if resource was found
     def parse_response!
       ensure_rate_limit!
       ensure_resource_found!
     end
 
+    # Holds the meta data
+    # @see https://docs.postmen.com/#meta API Documentation
+    # @return [Hash]
     def meta
       @meta ||= parsed_response[:meta]
     end
 
+    # Parses the json response
+    # @return [Hash]
     def parsed_response
       @parsed_response ||= JSON.parse(body, symbolize_names: true)
     end
 
+    # Checks if rate limit was exceeded
     def rate_limit_exceeded?
       code == 429
     end
 
+    # Returns number of remaining API calls
     def remaining_api_calls
       Integer(headers['X-RateLimit-Remaining'])
     end
 
+    # Returns current API rate limit
     def api_rate_limit
       Integer(headers['X-RateLimit-Limit'])
     end
 
+    # Returns Unix timestamp when rate limit will be reset.
+    # @return [Integer] timestamp
     def api_rate_limit_reset
       Integer(headers['X-RateLimit-Reset'])
     end
 
+    # Return time when rate limit will be reset.
+    # @return [Time]
     def api_rate_limit_reset_at
       Time.at(api_rate_limit_reset)
     end
 
     private
 
+    # Guard method, checking if rate limit was not exceeded
+    # @api private
     def ensure_rate_limit!
       raise RateLimitExceeded, self if rate_limit_exceeded?
     end
 
+    # Guard method, checking if resource was found.
+    # @api private
     def ensure_resource_found!
       raise ResourceNotFound, self if meta[:code] == 4153
     end

data/lib/postmen/shipment.rb

@@ -0,0 +1,18 @@
+class Postmen
+  # Shipment object
+  #
+  # @see https://docs.postmen.com/api.html#shipment API documentation
+  class Shipment < Dry::Struct
+    constructor_type :strict_with_defaults
+
+    attribute :ship_from, Types::Address
+    attribute :ship_to, Types::Address
+    attribute :parcels, Types::Array.member(Parcel)
+
+    # Converts object to hash
+    # @return [Hash]
+    def to_hash
+      super.reject { |_k, v| v.nil? }
+    end
+  end
+end

data/lib/postmen/shipper_account.rb

@@ -0,0 +1,68 @@
+class Postmen
+  # Shipper account object
+  # (brief information for rate and manifest responses)
+  # @see https://docs.postmen.com/api.html#shipper-account-information API Documentation
+  class ShipperAccount < Dry::Struct
+    attribute :id, Types::UUID
+    attribute :address, Types::Address
+    attribute :slug, Types::String
+    attribute :description, Types::String
+    attribute :type, Types::ShipperAccountTypes
+    attribute :timezone, Types::Timezone
+    attribute :created_at, Types::DateTime
+    attribute :updated_at, Types::DateTime
+
+    # Returns all ShipperAccounts
+    #
+    # @see ShipperAccountCollection#all
+    # @return [ShipperAccountCollection] Collection of ShipperAccounts
+    def self.all(options = {})
+      ShipperAccountCollection.all(options)
+    end
+
+    # Fetches single ShipperAccount
+    #
+    # @see ShipperAccountCollection#find
+    # @return [ShipperAccount]
+    def self.find(id)
+      ShipperAccountCollection.find(id)
+    end
+
+    # Creates an instance of ShipperAccount
+    #
+    # @see ShipperAccountCollection#create
+    # @return [ShipperAccount]
+    def self.create(params)
+      ShipperAccountCollection.create(params)
+    end
+
+    # Deletes given ShipperAccount
+    #
+    # @see https://docs.postmen.com/api.html#shipper-accounts-delete-a-shipper-account API Documentation
+    def destroy
+      Connection.new.delete("/shipper-accounts/#{@id}")
+    end
+
+    # Update a ShipperAccount credentials
+    #
+    # @see https://docs.postmen.com/api.html#shipper-accounts-update-a-shipper-account-credentials
+    # @return [ShipperAccount] Updated ShipperAccount resource
+    def update_credentials(params = {})
+      Connection.new.put(
+        "/shipper-accounts/#{@id}/credentials",
+        ShipperAccountUpdateCredentialsQuery.new(params).to_hash
+      )
+    end
+
+    # Update a shipper account information
+    #
+    # @see https://docs.postmen.com/api.html#shipper-accounts-update-a-shipper-account-information API Documentation
+    # @example
+    #   .update(description: "Your new description")
+    #   .update(address: {})
+    # @return [ShipperAccount] Updated ShipperAccount resource
+    def update(params = {})
+      Connection.new.put("/shipper-accounts/#{@id}/info", ShipperAccountUpdateQuery.new(params.merge(subject: self)).to_query)
+    end
+  end
+end

data/lib/postmen/shipper_account_collection.rb

@@ -0,0 +1,39 @@
+class Postmen
+  # This class wraps the array of ShipperAccount models
+  class ShipperAccountCollection
+    include CollectionProxy
+
+    model ShipperAccount
+    key :shipper_accounts
+
+    # Fetch all shipper accounts.
+    #
+    # @param options [Hash] Options for the query.
+    # @see https://docs.postmen.com/api.html#shipper-accounts-list-all-shipper-accounts API documentation
+    # @example
+    #   .all # Returns all shipper accounts, default query.
+    #   .all(slug: :aramex) # Returns only Shipper accounts from Aramex
+    def self.all(options = {})
+      new(Connection.new.get('/shipper-accounts', ShipperAccountQuery.new(options).to_query).parsed_response)
+    end
+
+    # Fetch single ShipperAccount
+    #
+    # @param id [UUID] ShipperAccount UUID
+    # @see https://docs.postmen.com/api.html#shipper-accounts-retrieve-a-shipper-account API documentation
+    # @return [ShipperAccount]
+    # @raise ResourceNotFound if ShipperAccount with given id was not found
+    def self.find(id)
+      get(Connection.new.get("/shipper-accounts/#{id}").parsed_response)
+    end
+
+    # Creates a ShipperAccount
+    #
+    # @param params [Hash] ShipperAccount params
+    # @see https://docs.postmen.com/api.html#shipper-accounts-create-a-shipper-account API documentation
+    # @return [ShipperAccount]
+    def self.create(params)
+      ShipperAccount.new(Connection.new.post('/shipper-accounts', CreateShipperAccountQuery.new(params).to_query).parsed_response[:data])
+    end
+  end
+end

data/lib/postmen/types/address.rb

@@ -0,0 +1,31 @@
+class Postmen
+  module Types
+    # Address object
+    #
+    # @see https://docs.postmen.com/api.html#address API Documentation
+    class Address < Dry::Struct
+      constructor_type :strict_with_defaults
+
+      attribute :country, Types::Country
+      attribute :contact_name, Types::String.optional.default(nil)
+      attribute :phone, Types::String.optional.default(nil)
+      attribute :fax, Types::String.optional.default(nil)
+      attribute :email, Types::String.optional.default(nil)
+      attribute :company_name, Types::String.optional.default(nil)
+      attribute :street1, Types::String.optional.default(nil)
+      attribute :street2, Types::String.optional.default(nil)
+      attribute :street3, Types::String.optional.default(nil)
+      attribute :city, Types::String.optional.default(nil)
+      attribute :state, Types::String.optional.default(nil)
+      attribute :postal_code, Types::String.optional.default(nil)
+      attribute :type, Types::AddressType.optional.default(nil)
+      attribute :tax_id, Types::String.optional.default(nil)
+
+      # Converts object to hash
+      # @return [Hash]
+      def to_hash
+        super.reject { |_k, v| v.nil? }
+      end
+    end
+  end
+end

data/lib/postmen/types/aes.rb

@@ -0,0 +1,11 @@
+class Postmen
+  module Types
+    # EEI type - AES - used in Customs object
+    # @see Customs
+    # @see https://docs.postmen.com/api.html#aes API Documentation
+    class AES < Dry::Struct
+      attribute :type, Types::String
+      attribute :itn_number, Types::String
+    end
+  end
+end

data/lib/postmen/types/billing.rb

@@ -0,0 +1,9 @@
+class Postmen
+  module Types
+    # Billing object
+    #
+    # @see https://docs.postmen.com/api.html#billing API Documentation
+    class Billing < Dry::Struct
+    end
+  end
+end

data/lib/postmen/types/brief_shipper_account.rb

@@ -0,0 +1,12 @@
+class Postmen
+  module Types
+    # Shipper account object
+    # (brief information for rate and manifest responses)
+    # @see https://docs.postmen.com/api.html#shipper-account-information API Documentation
+    class BriefShipperAccount < Dry::Struct
+      attribute :id, Types::UUID
+      attribute :slug, Types::String
+      attribute :description, Types::String
+    end
+  end
+end

data/lib/postmen/types/customs.rb

@@ -0,0 +1,16 @@
+class Postmen
+  module Types
+    # Customs object
+    # @see https://docs.postmen.com/api.html#customs API Documentation
+    class Customs < Dry::Struct
+      constructor_type :schema
+
+      attribute :purpose, Types::CustomsPurpose
+      attribute :terms_of_trade, Types::TermsOfTrade
+      attribute :eei, Types::AES | Types::NoEEI
+      attribute :billing, Types::CustomsBilling
+      attribute :importer_address, Address
+      attribute :passport, Passport
+    end
+  end
+end

data/lib/postmen/types/customs_billing.rb

@@ -0,0 +1,13 @@
+class Postmen
+  module Types
+    # Customs billing
+    #
+    # @see https://docs.postmen.com/api.html#customs-billing API Documentation
+    class CustomsBilling < Dry::Struct
+      constructor_type :schema
+
+      attribute :paid_by, Types::PaidBy
+      attribute :method, Types::PaymentMethod
+    end
+  end
+end

data/lib/postmen/types/detailed_charges.rb

@@ -0,0 +1,10 @@
+class Postmen
+  module Types
+    # Detailed Charges object
+    # @see https://docs.postmen.com/api.html#detailed-charges API Documentation
+    class DetailedCharges < Dry::Struct
+      attribute :type, Types::String
+      attribute :charge, Types::Money
+    end
+  end
+end

data/lib/postmen/types/dimension.rb

@@ -0,0 +1,12 @@
+class Postmen
+  module Types
+    # Dimension
+    # @see https://docs.postmen.com/api.html#dimension API Documentation
+    class Dimension < Dry::Struct
+      attribute :width, Types::Float
+      attribute :height, Types::Float
+      attribute :depth, Types::Float
+      attribute :unit, Types::DimensionUnit
+    end
+  end
+end

data/lib/postmen/types/invoice.rb

@@ -0,0 +1,9 @@
+class Postmen
+  module Types
+    # Invoice object
+    #
+    # @see https://docs.postmen.com/api.html#a-invoice-file-object
+    class Invoice < Dry::Struct
+    end
+  end
+end

data/lib/postmen/types/item.rb

@@ -0,0 +1,24 @@
+class Postmen
+  module Types
+    # Item - element of shippment
+    # @see https://docs.postmen.com/api.html#item API Documentation
+    class Item < Dry::Struct
+      constructor_type :schema
+
+      attribute :description, Types::String
+      attribute :quantity, Types::Int
+      attribute :price, Types::Money
+      attribute :weight, Types::Weight
+      attribute :item_id, Types::String
+      attribute :origin_country, Types::Country
+      attribute :sku, Types::String
+      attribute :hs_code, Types::String
+
+      # Converts object to hash
+      # @return [Hash]
+      def to_hash
+        super.reject { |_k, v| v.nil? }
+      end
+    end
+  end
+end

data/lib/postmen/types/money.rb

@@ -0,0 +1,10 @@
+class Postmen
+  module Types
+    # Money object
+    # @see https://docs.postmen.com/api.html#money API Documentation
+    class Money < Dry::Struct
+      attribute :amount, Types::Float
+      attribute :currency, Types::String
+    end
+  end
+end

data/lib/postmen/types/no_eei.rb

@@ -0,0 +1,11 @@
+class Postmen
+  module Types
+    # EEI type - no_eei - used in Customs object
+    # @see Customs
+    # @see https://docs.postmen.com/api.html#no_eei API Documentation
+    class NoEEI < Dry::Struct
+      attribute :type, Types::String
+      attribute :ftr_exemption, Types::FtrExemption
+    end
+  end
+end

data/lib/postmen/types/passport.rb

@@ -0,0 +1,21 @@
+class Postmen
+  module Types
+    # Passport object
+    #
+    # @see https://docs.postmen.com/api.html#passport API Documentation
+    class Passport < Dry::Struct
+      # Expected format for dates
+      # example value: 2017-01-19
+      DATE_FORMAT = '%F'.freeze
+
+      attribute :number, Types::String
+      attribute :issue_date, Types::Date
+
+      # Formats issue date to expected format
+      # @return [String]
+      def issue_date
+        super.strftime(DATE_FORMAT)
+      end
+    end
+  end
+end

data/lib/postmen/types/payment_method.rb

@@ -0,0 +1,13 @@
+class Postmen
+  module Types
+    # Payment method.
+    #
+    # @see https://docs.postmen.com/api.html#payment-method---account API Documentation
+    class PaymentMethod < Dry::Struct
+      attribute :type, Types::String
+      attribute :account_number, Types::String
+      attribute :postal_code, Types::String
+      attribute :country, Country
+    end
+  end
+end

data/lib/postmen/types/reference.rb

@@ -0,0 +1,9 @@
+class Postmen
+  module Types
+    # Object reference
+    # @see https://docs.postmen.com/api.html#reference API Documentation
+    class Reference < Dry::Struct
+      attribute :id, Types::UUID
+    end
+  end
+end

data/lib/postmen/types/uuid.rb

@@ -0,0 +1,10 @@
+class Postmen
+  module Types
+    # UUID Type
+    #
+    # @see https://en.wikipedia.org/wiki/Universally_unique_identifier Definition
+    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
+    )
+  end
+end

data/lib/postmen/types/weight.rb

@@ -0,0 +1,10 @@
+class Postmen
+  module Types
+    # Weight
+    # @see https://docs.postmen.com/api.html#weight API Documentation
+    class Weight < Dry::Struct
+      attribute :unit, Types::WeightUnit
+      attribute :value, Types::Float
+    end
+  end
+end

data/lib/postmen/types.rb

@@ -1,14 +1,20 @@
+# Load '.maybe' extension for DRY::Types
 Dry::Types.load_extensions(:maybe)
 
 class Postmen
+  # This module holds all definitions of simple types used in the API
   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
+    # Possible statuses for Rates.
+    RateStatuses = Types::String.enum(
+      'calculating',
+      'calculated',
+      'failed'
     )
 
-    Statuses = Types::String.enum(
+    # Possible statuses for Labels.
+    LabelStatuses = Types::String.enum(
       'creating',
       'created',
       'cancelling',
@@ -18,8 +24,33 @@ class Postmen
       'failed'
     )
 
-    Reference = Types::Hash.schema(id: Types::UUID)
-    Shipment = Types::Hash
+    # Possible statuses for Manifest
+    ManifestStatuses = Types::String.enum(
+      'manifesting',
+      'manifested',
+      'failed'
+    )
+
+    # Type of the address
+    # @see Address
+    AddressType = Types::String.enum(
+      'business',
+      'residential'
+    )
+
+    # List of possible Shipper Account Types
+    ShipperAccountTypes = Types::String.enum(
+      'user',
+      'user_prepaid'
+    )
+
+    # Timezone (use IANA name)
+    Timezone = Types::String
+
+    # Name of the country
+    Country = Types::String
+
+    # Paper size
     PaperSize = Types::String.enum(
       '4x4',
       '4x6',
@@ -30,8 +61,82 @@ class Postmen
       'default'
     )
 
-    Invoice = Types::Hash
-    Billing = Types::Hash
-    Customs = Types::Hash
+    # Purpose used in customs object
+    #
+    # @see https://docs.postmen.com/api.html#customs API Documentation
+    CustomsPurpose = Types::String.enum(
+      'gift',
+      'merchandise',
+      'sample',
+      'return',
+      'repair'
+    )
+
+    # Paid by, used in customs billing.
+    #
+    # @see CustomsBilling
+    # @see https://docs.postmen.com/api.html#customs-billing API Documentation
+    PaidBy = Types::String.enum(
+      'shipper',
+      'recipient',
+      'third_party'
+    )
+
+    # Terms of trade - used in customs object
+    #
+    # @see Customs
+    # @see https://docs.postmen.com/api.html#customs API Documentation
+    TermsOfTrade = Types::String.enum(
+      'dat',
+      'ddu',
+      'ddp',
+      'dap'
+    )
+
+    # FTR Exemption - used in NoEEI object
+    # @see NoEEI
+    # @see https://docs.postmen.com/api.html#no_eei API Documentation
+    FtrExemption = Types::String.enum(
+      'noeei_30_37_a',
+      'noeei_30_37_h',
+      'noeei_30_36'
+    )
+
+    # Unit of weight - used in Weight object
+    # @see Weight
+    WeightUnit = Types::String.enum(
+      'lb',
+      'kg',
+      'oz',
+      'g'
+    )
+
+    # Unit for dimension - used in Dimension object
+    # @see Dimension
+    DimensionUnit = Types::String.enum(
+      'cm',
+      'in',
+      'mm',
+      'm',
+      'ft',
+      'yd'
+    )
   end
 end
+require_relative 'types/address'
+require_relative 'types/invoice'
+require_relative 'types/weight'
+require_relative 'types/passport'
+require_relative 'types/uuid'
+require_relative 'types/reference'
+require_relative 'types/payment_method'
+require_relative 'types/brief_shipper_account'
+require_relative 'types/dimension'
+require_relative 'types/billing'
+require_relative 'types/money'
+require_relative 'types/item'
+require_relative 'types/customs_billing'
+require_relative 'types/aes'
+require_relative 'types/no_eei'
+require_relative 'types/customs'
+require_relative 'types/detailed_charges'

data/lib/postmen/version.rb

@@ -1,3 +1,4 @@
 class Postmen
-  VERSION = '0.1.0'.freeze
+  # SDK Version
+  VERSION = '1.0.0-alpha.1'.freeze
 end