pombo 1.0.0.pre.alpha → 1.0.0

data/lib/pombo/exception.rb

@@ -1,7 +1,16 @@
 module Pombo
-  class Error < StandardError; end
+  # Generic exception
+  class Error < StandardError
+    def initializer(msg = nil)
+      super
 
+      Pombo.logger.error('exception.pombo') { msg }
+    end
+  end
+
+  # Exception triggered to manage settings
   class ConfigurationError < Pombo::Error; end
 
+  # Exception triggered when managing the webservice
   class WebserviceError < Pombo::Error; end
 end

data/lib/pombo/logger.rb

@@ -0,0 +1,17 @@
+require 'logger'
+
+module Pombo
+  # Used to extend the Logger class and customize the message
+  # @exemple
+  #   Pombo.logger.info('event.namespace'){ 'Any error message' }
+  #   # => 2016-05-13 15:15:49 -0300 | POMBO | event.namespace | INFO: Any error message
+  class Logger < ::Logger
+
+    private
+
+    def format_message(severity, datetime, progname, msg)
+      "#{ datetime } | POMBO | #{ progname } | #{ severity }: #{ msg }\n"
+    end
+
+  end
+end

data/lib/pombo/package.rb

@@ -1,4 +1,25 @@
 module Pombo
+  # This is the composite package of items that will be sent
+  #
+  # @example
+  #   package = Pombo::Package.new ({
+  #     destination_zip_code: '29999000',
+  #     origin_zip_code: '28888000',
+  #     services: "40010",
+  #     in_hand: false,
+  #     delivery_notice: false
+  #   })
+  #   # => <Pombo::Package:0x007fcfd32080f0 @items=[], @length=0, @height=0, @width=0, @declared_value=0, @destination_zip_code="29999000", @origin_zip_code="28888000">
+  #
+  #   package.add_item weight: 5, length: 4, height: 3, width: 5, diameter: 0
+  #   package.add_item weight: 4, length: 10, height: 5, width: 5, diameter: 5, format: Pombo::Package::Format.find(:roll).code
+  #   package.in_hand? # => false
+  #   package.delivery_notice? # => false
+  #   package.weight # => 9
+  #   package.diameter # => 0
+  #   package.format # => 1
+  #   package.volume # => 158.17000000000002
+  #   package.single_item? # => false
   class Package
     attr_accessor :destination_zip_code, :origin_zip_code, :declared_value
     attr_reader :items, :length, :height, :width, :services
@@ -9,6 +30,10 @@ module Pombo
       args.each { |key, value| __send__("#{ key }=", value) }
     end
 
+    # @!method in_hand?
+    #   Informs you are contracted delivery in hand service
+    # @!method delivery_notice?
+    #   Informs you are contracted delivery notice service
     %i[in_hand delivery_notice].each do |method|
       define_method("#{ method }?"){ instance_variable_get "@#{ method }" }
     end
@@ -20,45 +45,79 @@ module Pombo
         elsif Pombo::Support::FALSE_VALUES.include? value
           instance_variable_set "@#{ method }", false
         else
-          raise TypeError, "no implicit conversion of #{ value } into True or False"
+          raise TypeError, "no implicit conversion of #{ value } into TrueClass or FalseClass"
         end
       end
     end
 
+    # @!method length
+    #   returns the length of the package or the format if `min_package` is true
+    # @!method height
+    #   returns the height of the package or the format if `min_package` is true
+    # @!method width
+    #   returns the width of the package or the format if `min_package` is true
+    %i[length height width].each do |method|
+      define_method("#{ method }") do
+        value = instance_variable_get("@#{ method }")
+        return value unless Pombo.configurations.min_package?
+
+        current_format = Pombo::Package::Format.find(format)
+        [value, current_format.send("min_#{ method }")].max
+      end
+    end
+
+    # The services used to send the package
+    # @return [Array<String>] codes services
     def services=(services)
       @services = services.kind_of?(Array) ? services : [services]
     end
 
+    # It allows you to add an item to the package
+    # @return [Pombo::Package::Item] the added item
+    #
+    # @example
+    #   item = Pombo::Package::Item.new weight: 5, length: 4, height: 3, width: 5, diameter: 0
+    #   package.add_item item
+    #
+    #   # => or
+    #
+    #   package.add_item weight: 5, length: 4, height: 3, width: 5, diameter: 0
     def add_item(item = nil, **args)
       item = if item.kind_of?(Pombo::Package::Item)
-                  item
-                else
-                  Pombo::Package::Item.new(args)
-                end
+               item
+             else
+               Pombo::Package::Item.new(args)
+             end
 
       @items << item
       update_measures
       item
     end
 
+    # @return [Float] the total weight of the items
     def weight
       @items.inject(0) { |sum, item| sum += item.weight }
     end
 
+    # @return [Float] the total diameter of the items
     def diameter
       return @items.first.diameter if single_item? && format == Pombo::Package::Format.find(:roll).code
       0
     end
 
+    # @return [Fixnum] the code of the packet format
+    #   For packages with more than one item format will be 1 (:box)
     def format
       return @items.first.format if single_item?
       Pombo::Package::Format.find(:box).code
     end
 
+    # @return [Float] the total volume of the items
     def volume
       @items.inject(0) { |sum, item| sum += item.volume }
     end
 
+    # @return [Boolean] tells if the package contains only one item
     def single_item?
       @items.size == 1 && @items.first.quantity == 1
     end
@@ -66,7 +125,16 @@ module Pombo
     private
 
     def update_measures
-      @length = @height = @width = Math.cbrt volume
+      if single_item?
+        item = @items.first
+        @length, @height, @width = item.length, item.height, item.width
+      else
+        @length = @height = @width = Math.cbrt volume
+      end
+    end
+
+    def min_measure_for(measure, value)
+
     end
   end
 end

data/lib/pombo/package/format.rb

@@ -1,24 +1,44 @@
 module Pombo
   class Package
+    # The formats are pre-defined objects with the information provided by the Correios
     module Format
-      @@all_formats = {
-        '1' => OpenStruct.new(code: 1, name: 'Caixa/Pacote', max_length: 105, min_length: 16, max_height: 105, min_height: 2, max_width: 105, min_width: 11, max_dimension: 200),
-        '2' => OpenStruct.new(code: 2, name: 'Rolo/Prisma', max_length: 105, min_length: 18, max_diameter: 91, min_diameter: 5, max_dimension: 200),
-        '3' => OpenStruct.new(code: 3, name: 'Envelope', max_length: 60, min_length: 16, max_width: 60, min_width: 11, max_weight: 1),
-      }
-
+      # List all formats supported by delivery services
+      # @return [Array<OpenStruct>] with the data structure representing a format
+      #
+      # @example
+      #     Pombo::Package::Format.all
+      #     # => [
+      #     # =>    #<OpenStruct code=3, name="Envelope", max_length=60, min_length=16, max_width=60, min_width=11, max_weight=1>
+      #     # =>    ....
+      #     # => ]
+      #
       def self.all
-        @@all_formats.values
+        [
+          OpenStruct.new(code: 1, name: Pombo.t('formats.1'), max_length: 105, min_length: 16, max_height: 105, min_height: 2, max_width: 105, min_width: 11, max_dimension: 200),
+          OpenStruct.new(code: 2, name: Pombo.t('formats.2'), max_length: 105, min_length: 18, max_diameter: 91, min_diameter: 5, max_dimension: 200),
+          OpenStruct.new(code: 3, name: Pombo.t('formats.3'), max_length: 60, min_length: 16, max_width: 60, min_width: 11, max_weight: 1)
+        ]
       end
 
+      # Find a specific format by code or by name
+      # @return [OpenStruct] the data structure representing a format
+      # @param code [String] code or the format name, to box `1, box or package`, to roll `2, roll or prism` and to envelope `3 or envelope`
+      # @example
+      #     Pombo::Package::Format.find '3'
+      #     # => #<OpenStruct code=3, name="Envelope", max_length=60, min_length=16, max_width=60, min_width=11, max_weight=1>
+      #
+      #     # => Or
+      #
+      #     Pombo::Package::Format.find 'envelope'
+      #     # => #<OpenStruct code=3, name="Envelope", max_length=60, min_length=16, max_width=60, min_width=11, max_weight=1>
       def self.find(code)
         case code.to_s
         when '1', 'box', 'package'
-          @@all_formats.values_at('1').first
+          all[0]
         when '2', 'roll', 'prism'
-          @@all_formats.values_at('2').first
+          all[1]
         when '3', 'envelope'
-          @@all_formats.values_at('3').first
+          all[2]
         end
       end
     end

data/lib/pombo/package/item.rb

@@ -1,4 +1,7 @@
 module Pombo
+  # Item is the object that will be sent in the package through the Brazilian Post Service
+  #
+  # By default the quantity is 1 and the format is +Pombo::Package::Format.find(:box).code+
   class Package::Item
     attr_accessor :weight, :length, :height, :width, :diameter, :quantity, :format
 
@@ -7,6 +10,8 @@ module Pombo
       args.each { |key, value| __send__("#{ key }=", value) }
     end
 
+    # Calculates the volume item in accordance with the format
+    # @return [Float] the volume value
     def volume
       case format
       when Pombo::Package::Format.find(:box).code

data/lib/pombo/services.rb

@@ -1,52 +1,88 @@
 require 'ostruct'
 
 module Pombo
+  # Contains delivery services
   module Services
-    @@all_pac = {
-      "41106" => OpenStruct.new(code: "41106", max_weight: 30, name: 'PAC', description: 'PAC (sem contrato)'),
-      "41068" => OpenStruct.new(code: "41068", max_weight: 50, name: 'PAC', description: 'PAC (com contrato)'),
-      "41300" => OpenStruct.new(code: "41300", max_weight: 600, name: 'PAC GF', description: 'PAC (grandes formatos)')
-    }
-
-    @@all_sedex = {
-      "40010" => OpenStruct.new(code: "40010", max_weight: 30, name: 'SEDEX', description: 'SEDEX (sem contrato)'),
-      "40045" => OpenStruct.new(code: "40045", max_weight: 30, name: 'SEDEX a cobrar', description: 'SEDEX a cobrar (sem contrato)'),
-      "40126" => OpenStruct.new(code: "40126", max_weight: 30, name: 'SEDEX a cobrar', description: 'SEDEX a cobrar (com contrato)'),
-      "40215" => OpenStruct.new(code: "40215", max_weight: 10, name: 'SEDEX 10', description: 'SEDEX 10 (sem contrato)'),
-      "40290" => OpenStruct.new(code: "40290", max_weight: 10, name: 'SEDEX hoje', description: 'SEDEX hoje (sem contrato)'),
-      "40096" => OpenStruct.new(code: "40096", max_weight: 30, name: 'SEDEX', description: 'SEDEX (com contrato)'),
-      "40436" => OpenStruct.new(code: "40436", max_weight: 30, name: 'SEDEX', description: 'SEDEX (com contrato)'),
-      "40444" => OpenStruct.new(code: "40444", max_weight: 30, name: 'SEDEX', description: 'SEDEX (com contrato)'),
-      "40568" => OpenStruct.new(code: "40568", max_weight: 30, name: 'SEDEX', description: 'SEDEX (com contrato)'),
-      "40606" => OpenStruct.new(code: "40606", max_weight: 30, name: 'SEDEX', description: 'SEDEX (com contrato)')
-    }
-
-    @@all_e_sedex = {
-      "81019" => OpenStruct.new(code: "81019", max_weight: 15, name: 'E-SEDEX', description: 'E-SEDEX (com contrato)'),
-      "81027" => OpenStruct.new(code: "81027", max_weight: 15, name: 'E-SEDEX', description: 'E-SEDEX Prioritário (com contrato)'),
-      "81035" => OpenStruct.new(code: "81035", max_weight: 15, name: 'E-SEDEX', description: 'E-SEDEX Express (com contrato)'),
-      "81868" => OpenStruct.new(code: "81868", max_weight: 15, name: 'E-SEDEX', description: 'E-SEDEX (com contrato, grupo 1)'),
-      "81833" => OpenStruct.new(code: "81833", max_weight: 15, name: 'E-SEDEX', description: 'E-SEDEX (com contrato, grupo 2)'),
-      "81850" => OpenStruct.new(code: "81850", max_weight: 15, name: 'E-SEDEX', description: 'E-SEDEX (com contrato, grupo 3)')
-    }
-
-    @@all_services = @@all_pac.merge(@@all_sedex).merge(@@all_e_sedex)
-
+    # List all services supported
+    # @param service [Symbol] group services, `:pac`, `sedex` or `e_sedex`
+    # @return [Array<OpenStruct>] with the data structure representing a service
+    #
+    # @example
+    #     Pombo::Services.all
+    #     # => [
+    #     # =>    #<OpenStruct code="41106", max_weight=30, name="PAC", description="PAC (without contract)">,
+    #     # =>    ....
+    #     # => ]
+    #
+    # Listing all the services of a group
+    #
+    # @example
+    #     Pombo::Services.all :pac
+    #     # => [
+    #     # =>    #<OpenStruct code="41106", max_weight=30, name="PAC", description="PAC (without contract)">,
+    #     # =>    ....
+    #     # => ]
+    #
     def self.all(service = nil)
       case service
       when :pac
-        @@all_pac.values
+        all_pac.values
       when :sedex
-        @@all_sedex.values
+        all_sedex.values
       when :e_sedex
-        @@all_e_sedex.values
+        all_e_sedex.values
       else
-        @@all_pac.values + @@all_sedex.values + @@all_e_sedex.values
+        all_pac.values + all_sedex.values + all_e_sedex.values
       end
     end
 
+    # Search for a service code
+    # @return [OpenStruct] the data structure representing a service
+    # @example
+    #     Pombo::Services.find "41106"
+    #     # => #<OpenStruct code="41106", max_weight=30, name="PAC", description="PAC (without contract)">
     def self.find(code)
-     @@all_services.values_at(code).first
+      all_services.values_at(code).first
+    end
+
+    private
+
+    def self.all_pac
+      {
+        "41106" => OpenStruct.new(code: "41106", max_weight: 30, name: 'PAC', description: Pombo.t('services.pac.41106')),
+        "41068" => OpenStruct.new(code: "41068", max_weight: 50, name: 'PAC', description: Pombo.t('services.pac.41068')),
+        "41300" => OpenStruct.new(code: "41300", max_weight: 600, name: 'PAC GF', description: Pombo.t('services.pac.41300'))
+      }
+    end
+
+    def self.all_sedex
+      {
+        "40010" => OpenStruct.new(code: "40010", max_weight: 30, name: 'SEDEX', description: Pombo.t('services.sedex.40010')),
+        "40045" => OpenStruct.new(code: "40045", max_weight: 30, name: 'SEDEX a cobrar', description: Pombo.t('services.sedex.40045')),
+        "40126" => OpenStruct.new(code: "40126", max_weight: 30, name: 'SEDEX a cobrar', description: Pombo.t('services.sedex.40126')),
+        "40215" => OpenStruct.new(code: "40215", max_weight: 10, name: 'SEDEX 10', description: Pombo.t('services.sedex.40215')),
+        "40290" => OpenStruct.new(code: "40290", max_weight: 10, name: 'SEDEX hoje', description: Pombo.t('services.sedex.40290')),
+        "40096" => OpenStruct.new(code: "40096", max_weight: 30, name: 'SEDEX', description: Pombo.t('services.sedex.40096')),
+        "40436" => OpenStruct.new(code: "40436", max_weight: 30, name: 'SEDEX', description: Pombo.t('services.sedex.40436')),
+        "40444" => OpenStruct.new(code: "40444", max_weight: 30, name: 'SEDEX', description: Pombo.t('services.sedex.40444')),
+        "40568" => OpenStruct.new(code: "40568", max_weight: 30, name: 'SEDEX', description: Pombo.t('services.sedex.40568')),
+        "40606" => OpenStruct.new(code: "40606", max_weight: 30, name: 'SEDEX', description: Pombo.t('services.sedex.40606'))
+      }
+    end
+
+    def self.all_e_sedex
+      {
+        "81019" => OpenStruct.new(code: "81019", max_weight: 15, name: 'E-SEDEX', description: Pombo.t('services.e_sedex.81019')),
+        "81027" => OpenStruct.new(code: "81027", max_weight: 15, name: 'E-SEDEX', description: Pombo.t('services.e_sedex.81027')),
+        "81035" => OpenStruct.new(code: "81035", max_weight: 15, name: 'E-SEDEX', description: Pombo.t('services.e_sedex.81035')),
+        "81868" => OpenStruct.new(code: "81868", max_weight: 15, name: 'E-SEDEX', description: Pombo.t('services.e_sedex.81868')),
+        "81833" => OpenStruct.new(code: "81833", max_weight: 15, name: 'E-SEDEX', description: Pombo.t('services.e_sedex.81833')),
+        "81850" => OpenStruct.new(code: "81850", max_weight: 15, name: 'E-SEDEX', description: Pombo.t('services.e_sedex.81850'))
+      }
+    end
+
+    def self.all_services
+      all_pac.merge(all_sedex).merge(all_e_sedex)
     end
   end
 end

data/lib/pombo/support.rb

@@ -1,13 +1,26 @@
 module Pombo
+  # Generic methods
   module Support
     TRUE_VALUES  = [true, 1, '1', 't', 'T', 'true', 'TRUE']
     FALSE_VALUES = [false, 0, '0', 'f', 'F', 'false', 'FALSE']
 
+    # Convert the string of Brazilian currency to float
+    # @return [String] the converted string pattern R$ (unit brazilian) to pattern Float.
+    # @raise [TypeError] if the value is not a String
+    # @example
+    #   Pombo::Support.str_real_to_float('2,00')
+    #   # => '2.00'
     def self.str_real_to_float(value)
       raise TypeError, "no implicit conversion of #{ value.class.name } into String" unless value.kind_of? String
-      value.gsub(',','.').to_f
+      value.tr(',','.').to_f
     end
 
+    # Used to convert Boolean values to String
+    # @param [Boolean] the value to be converted
+    # @return [String] the string representation of a boolean. 'S' to +true+ and 'N' to +false+
+    # @example
+    #   Pombo::Support.boolean_to_string(true)
+    #   # => 'S'
     def self.boolean_to_string(value)
       value ? 'S' : 'N'
     end

data/lib/pombo/version.rb

@@ -1,3 +1,3 @@
 module Pombo
-  VERSION = "1.0.0.pre.alpha"
+  VERSION = "1.0.0"
 end

data/lib/pombo/webservice.rb

@@ -1,4 +1,5 @@
 module Pombo
+  # Namespace for webservices
   module Webservice
   end
 end

data/lib/pombo/webservice/base.rb

@@ -3,9 +3,12 @@ require 'net/http'
 
 module Pombo
   module Webservice
+    # Class contains the base to make requests
+    # @abstract
     class Base
 
       def self.get(url, request = nil)
+        Pombo.logger.info('start_request.webservice') { "GET request: #{ url }" }
         uri = URI.parse url
         uri.query = request.to_param unless request.nil?
         http_request = Net::HTTP::Get.new uri
@@ -22,7 +25,9 @@ module Pombo
         http = Net::HTTP.new host, port
         #http.set_debug_output($stdout)
         http.open_timeout = Pombo.configurations.request_timeout
-        http.request(http_request)
+        response = http.request(http_request)
+        Pombo.logger.info('end_request.webservice') { "GET #{ response.code } response: #{ response.body }" }
+        response
       end
     end
   end

data/lib/pombo/webservice/cpp.rb

@@ -7,20 +7,21 @@ module Pombo
       URL      = "#{ PROTOCOL }://#{ HOST }/calculador/CalcPrecoPrazo.asmx"
 
       def self.shipping(package)
-        url = "#{ URL }/CalcPrecoPrazo"
-        response = Response.new get(url, ShippingRequest.new(package))
-        response.body
+        resource "#{ URL }/CalcPrecoPrazo", ShippingRequest.new(package)
       end
 
       def self.delivery_time(package)
-        url = "#{ URL }/CalcPrazo"
-        response = Response.new get(url, DeliveryTimeRequest.new(package))
-        response.body
+        resource "#{ URL }/CalcPrazo", DeliveryTimeRequest.new(package)
       end
 
       def self.shipping_value(package)
-        url = "#{ URL }/CalcPreco"
-        response = Response.new get(url, ShippingValueRequest.new(package))
+        resource "#{ URL }/CalcPreco", ShippingValueRequest.new(package)
+      end
+
+      private
+
+      def self.resource(url, request)
+        response = Response.new get(url, request)
         response.body
       end
     end