cdek_api_client 0.1.0 → 0.2.0

data/lib/cdek_api_client/entities/location.rb

@@ -2,6 +2,8 @@
 
 module CDEKApiClient
   module Entities
+    # Represents a location in the CDEK API.
+    # Each location has attributes such as code, city, and address.
     class Location
       include Validatable
 
@@ -11,6 +13,12 @@ module CDEKApiClient
       validates :city, type: :string
       validates :address, type: :string
 
+      # Initializes a new Location object.
+      #
+      # @param code [Integer] the code of the location.
+      # @param city [String, nil] the city of the location.
+      # @param address [String, nil] the address of the location.
+      # @raise [ArgumentError] if any attribute validation fails.
       def initialize(code:, city: nil, address: nil)
         @code = code
         @city = city
@@ -18,6 +26,9 @@ module CDEKApiClient
         validate!
       end
 
+      # Converts the Location object to a JSON representation.
+      #
+      # @return [String] the JSON representation of the Location.
       def to_json(*_args)
         {
           code: @code,

data/lib/cdek_api_client/entities/order_data.rb

@@ -7,6 +7,8 @@ require_relative 'sender'
 
 module CDEKApiClient
   module Entities
+    # Represents the data required to create an order in the CDEK API.
+    # Each order includes attributes such as type, number, tariff code, locations, recipient, sender, and packages.
     class OrderData
       include Validatable
 
@@ -23,6 +25,21 @@ module CDEKApiClient
       validates :packages, type: :array, presence: true, items: [Package]
       validates :comment, type: :string
 
+      # Initializes a new OrderData object.
+      #
+      # @param type [Integer] the type of the order.
+      # @param number [String] the order number.
+      # @param tariff_code [Integer] the tariff code.
+      # @param from_location [Location] the location details from where the order is shipped.
+      # @param to_location [Location] the location details to where the order is shipped.
+      # @param recipient [Recipient] the recipient details.
+      # @param sender [Sender] the sender details.
+      # @param packages [Array<Package>] the list of packages.
+      # @param comment [String, nil] the comment for the order.
+      # @param shipment_point [String, nil] the shipment point.
+      # @param delivery_point [String, nil] the delivery point.
+      # @param services [Array, nil] additional services.
+      # @raise [ArgumentError] if any attribute validation fails.
       def initialize(type:, number:, tariff_code:, from_location:, to_location:, recipient:, sender:, packages:,
                      comment: nil, shipment_point: nil, delivery_point: nil, services: [])
         @type = type
@@ -40,6 +57,9 @@ module CDEKApiClient
         validate!
       end
 
+      # Converts the OrderData object to a JSON representation.
+      #
+      # @return [String] the JSON representation of the OrderData.
       def to_json(*_args)
         {
           type: @type,

data/lib/cdek_api_client/entities/package.rb

@@ -5,6 +5,8 @@ require_relative 'item'
 
 module CDEKApiClient
   module Entities
+    # Represents a package entity in the CDEK API.
+    # Each package includes attributes such as number, comment, height, length, weight, width, and items.
     class Package
       include Validatable
 
@@ -17,6 +19,16 @@ module CDEKApiClient
       validates :width, type: :integer, presence: true
       validates :items, type: :array, presence: true, items: [Item]
 
+      # Initializes a new Package object.
+      #
+      # @param number [String] the package number.
+      # @param comment [String] the comment for the package.
+      # @param height [Integer] the height of the package.
+      # @param length [Integer] the length of the package.
+      # @param weight [Integer] the weight of the package.
+      # @param width [Integer] the width of the package.
+      # @param items [Array<Item>] the list of items in the package.
+      # @raise [ArgumentError] if any attribute validation fails.
       def initialize(number:, comment:, height:, length:, weight:, width:, items:)
         @number = number
         @comment = comment
@@ -28,6 +40,9 @@ module CDEKApiClient
         validate!
       end
 
+      # Converts the Package object to a JSON representation.
+      #
+      # @return [String] the JSON representation of the Package.
       def to_json(*_args)
         {
           number: @number,

data/lib/cdek_api_client/entities/payment.rb

@@ -5,6 +5,8 @@ require_relative 'currency_mapper'
 
 module CDEKApiClient
   module Entities
+    # Represents a payment entity in the CDEK API.
+    # Each payment includes attributes such as value and currency.
     class Payment
       include Validatable
 
@@ -13,12 +15,20 @@ module CDEKApiClient
       validates :value, type: :integer, presence: true, positive: true
       validates :currency, type: :integer, presence: true
 
+      # Initializes a new Payment object.
+      #
+      # @param value [Integer] the payment value.
+      # @param currency [String] the currency code for the payment.
+      # @raise [ArgumentError] if any attribute validation fails.
       def initialize(value:, currency:)
         @value = value
-        @currency = CDEKApiClient::Entities::CurrencyMapper.to_code(currency)
+        @currency = CurrencyMapper.to_code(currency)
         validate!
       end
 
+      # Converts the Payment object to a JSON representation.
+      #
+      # @return [String] the JSON representation of the Payment.
       def to_json(*_args)
         {
           value: @value,

data/lib/cdek_api_client/entities/recipient.rb

@@ -4,6 +4,8 @@ require_relative 'validatable'
 
 module CDEKApiClient
   module Entities
+    # Represents a recipient entity in the CDEK API.
+    # Each recipient includes attributes such as name, phones, and email.
     class Recipient
       include Validatable
 
@@ -14,6 +16,12 @@ module CDEKApiClient
                          presence: true
       validates :email, type: :string, presence: true
 
+      # Initializes a new Recipient object.
+      #
+      # @param name [String] the name of the recipient.
+      # @param phones [Array<Hash>] the list of phone numbers for the recipient.
+      # @param email [String] the email address of the recipient.
+      # @raise [ArgumentError] if any attribute validation fails.
       def initialize(name:, phones:, email:)
         @name = name
         @phones = phones
@@ -21,6 +29,9 @@ module CDEKApiClient
         validate!
       end
 
+      # Converts the Recipient object to a JSON representation.
+      #
+      # @return [String] the JSON representation of the Recipient.
       def to_json(*_args)
         {
           name: @name,

data/lib/cdek_api_client/entities/sender.rb

@@ -4,6 +4,8 @@ require_relative 'validatable'
 
 module CDEKApiClient
   module Entities
+    # Represents a sender entity in the CDEK API.
+    # Each sender includes attributes such as name, phones, and email.
     class Sender
       include Validatable
 
@@ -14,6 +16,12 @@ module CDEKApiClient
                          presence: true
       validates :email, type: :string, presence: true
 
+      # Initializes a new Sender object.
+      #
+      # @param name [String] the name of the sender.
+      # @param phones [Array<Hash>] the list of phone numbers for the sender.
+      # @param email [String] the email address of the sender.
+      # @raise [ArgumentError] if any attribute validation fails.
       def initialize(name:, phones:, email:)
         @name = name
         @phones = phones
@@ -21,6 +29,9 @@ module CDEKApiClient
         validate!
       end
 
+      # Converts the Sender object to a JSON representation.
+      #
+      # @return [String] the JSON representation of the Sender.
       def to_json(*_args)
         {
           name: @name,

data/lib/cdek_api_client/entities/service.rb

@@ -5,6 +5,8 @@ require_relative 'payment'
 
 module CDEKApiClient
   module Entities
+    # Represents a service entity in the CDEK API.
+    # Each service includes attributes such as code, price, and name.
     class Service
       include Validatable
 
@@ -14,6 +16,12 @@ module CDEKApiClient
       validates :price, type: :integer, presence: true
       validates :name, type: :string, presence: true
 
+      # Initializes a new Service object.
+      #
+      # @param code [String] the code of the service.
+      # @param price [Integer] the price of the service.
+      # @param name [String] the name of the service.
+      # @raise [ArgumentError] if any attribute validation fails.
       def initialize(code:, price:, name:)
         @code = code
         @price = price
@@ -21,6 +29,9 @@ module CDEKApiClient
         validate!
       end
 
+      # Converts the Service object to a JSON representation.
+      #
+      # @return [String] the JSON representation of the Service.
       def to_json(*_args)
         {
           code: @code,

data/lib/cdek_api_client/entities/tariff_data.rb

@@ -5,6 +5,9 @@ require_relative 'currency_mapper'
 
 module CDEKApiClient
   module Entities
+    # Represents the data required to calculate a tariff in the CDEK API.
+    # Each tariff data includes attributes such as type, currency,
+    # from_location, to_location, packages, and tariff_code.
     class TariffData
       include Validatable
 
@@ -17,6 +20,15 @@ module CDEKApiClient
       validates :to_location, type: :object, presence: true
       validates :packages, type: :array, presence: true, items: [Package]
 
+      # Initializes a new TariffData object.
+      #
+      # @param type [Integer] the type of the tariff.
+      # @param currency [String] the currency code of the tariff.
+      # @param from_location [Location] the location from which the tariff calculation starts.
+      # @param to_location [Location] the destination location for the tariff calculation.
+      # @param packages [Array<Package>] the list of packages included in the tariff calculation.
+      # @param tariff_code [Integer] the tariff code.
+      # @raise [ArgumentError] if any attribute validation fails.
       def initialize(type:, currency:, from_location:, to_location:, packages:, tariff_code:)
         @type = type
         @currency = CurrencyMapper.to_code(currency)
@@ -27,6 +39,9 @@ module CDEKApiClient
         validate!
       end
 
+      # Converts the TariffData object to a JSON representation.
+      #
+      # @return [String] the JSON representation of the TariffData.
       def to_json(*_args)
         {
           type: @type,

data/lib/cdek_api_client/entities/validatable.rb

@@ -1,23 +1,39 @@
 # frozen_string_literal: true
 
+# Validatable module provides validation capabilities for entities.
 module CDEKApiClient
   module Entities
+    # This module provides validation capabilities for entities.
+    # It allows for presence and type validations on attributes.
     module Validatable
       def self.included(base)
         base.extend ClassMethods
       end
 
+      # Class methods for the Validatable module.
       module ClassMethods
+        # Defines validations for attributes.
+        #
+        # @param attribute [Symbol] the name of the attribute to validate.
+        # @param options [Hash] the validation options.
+        # @option options [Symbol] :type the expected type of the attribute.
+        # @option options [Boolean] :presence whether the attribute is required.
         def validates(attribute, options)
           @validations ||= {}
           @validations[attribute] = options
         end
 
+        # Returns the defined validations.
+        #
+        # @return [Hash] the defined validations.
         def validations
           @validations
         end
       end
 
+      # Validates the entity's attributes based on the defined validations.
+      #
+      # @raise [RuntimeError] if any validation fails.
       def validate!
         self.class.validations.each do |attribute, rule|
           value = send(attribute)
@@ -28,22 +44,30 @@ module CDEKApiClient
 
       private
 
+      # Validates the presence of an attribute.
+      #
+      # @param attribute [Symbol] the name of the attribute.
+      # @param value [Object] the value of the attribute.
+      # @param rule [Hash] the validation rule.
+      # @raise [RuntimeError] if the validation fails.
       def validate_presence(attribute, value, rule)
         raise "#{attribute} is required" if rule[:presence] && value.nil?
       end
 
+      # Validates the type of an attribute.
+      #
+      # @param attribute [Symbol] the name of the attribute.
+      # @param value [Object] the value of the attribute.
+      # @param rule [Hash] the validation rule.
+      # @raise [RuntimeError] if the validation fails.
       def validate_type(attribute, value, rule)
         case rule[:type]
         when :string
-          raise "#{attribute} must be a String" unless value.is_a?(String)
+          validate_string(attribute, value)
         when :integer
-          raise "#{attribute} must be an Integer" unless value.is_a?(Integer)
-
-          validate_positive(attribute, value, rule)
+          validate_integer(attribute, value, rule)
         when :array
-          raise "#{attribute} must be an Array" unless value.is_a?(Array)
-
-          validate_array_items(attribute, value, rule)
+          validate_array(attribute, value, rule)
         when :object
           validate_object(attribute, value, rule)
         when :hash
@@ -51,10 +75,55 @@ module CDEKApiClient
         end
       end
 
+      # Validates that a value is a string.
+      #
+      # @param attribute [Symbol] the name of the attribute.
+      # @param value [Object] the value of the attribute.
+      # @raise [RuntimeError] if the validation fails.
+      def validate_string(attribute, value)
+        raise "#{attribute} must be a String" unless value.is_a?(String)
+      end
+
+      # Validates that a value is an integer and optionally that it is positive.
+      #
+      # @param attribute [Symbol] the name of the attribute.
+      # @param value [Integer] the value of the attribute.
+      # @param rule [Hash] the validation rule.
+      # @raise [RuntimeError] if the validation fails.
+      def validate_integer(attribute, value, rule)
+        raise "#{attribute} must be an Integer" unless value.is_a?(Integer)
+
+        validate_positive(attribute, value, rule)
+      end
+
+      # Validates that a value is an array and its items.
+      #
+      # @param attribute [Symbol] the name of the attribute.
+      # @param array [Array] the value of the attribute.
+      # @param rule [Hash] the validation rule.
+      # @raise [RuntimeError] if the validation fails.
+      def validate_array(attribute, array, rule)
+        raise "#{attribute} must be an Array" unless array.is_a?(Array)
+
+        validate_array_items(attribute, array, rule)
+      end
+
+      # Validates that a value is positive.
+      #
+      # @param attribute [Symbol] the name of the attribute.
+      # @param value [Integer] the value of the attribute.
+      # @param rule [Hash] the validation rule.
+      # @raise [RuntimeError] if the validation fails.
       def validate_positive(attribute, value, rule)
         raise "#{attribute} must be a positive number" if rule[:positive] && value <= 0
       end
 
+      # Validates the items of an array.
+      #
+      # @param attribute [Symbol] the name of the attribute.
+      # @param array [Array] the value of the attribute.
+      # @param rule [Hash] the validation rule.
+      # @raise [RuntimeError] if the validation fails.
       def validate_array_items(attribute, array, rule)
         array.each do |item|
           if item.is_a?(Hash)
@@ -70,6 +139,12 @@ module CDEKApiClient
         end
       end
 
+      # Validates an object.
+      #
+      # @param _attribute [Symbol] the name of the attribute.
+      # @param object [Object] the value of the attribute.
+      # @param _rule [Hash] the validation rule.
+      # @raise [RuntimeError] if the validation fails.
       def validate_object(_attribute, object, _rule)
         object.class.validations.each do |attr, validation_rule|
           value = object.send(attr)
@@ -78,6 +153,12 @@ module CDEKApiClient
         end
       end
 
+      # Validates a hash.
+      #
+      # @param _attribute [Symbol] the name of the attribute.
+      # @param hash [Hash] the value of the attribute.
+      # @param rule [Hash] the validation rule.
+      # @raise [RuntimeError] if the validation fails.
       def validate_hash(_attribute, hash, rule)
         rule[:schema].each do |attr, validation_rule|
           value = hash[attr]

data/lib/cdek_api_client/entities/webhook.rb

@@ -4,6 +4,8 @@ require_relative 'validatable'
 
 module CDEKApiClient
   module Entities
+    # Represents a webhook entity in the CDEK API.
+    # Each webhook includes attributes such as url, type, and event types.
     class Webhook
       include Validatable
 
@@ -13,6 +15,12 @@ module CDEKApiClient
       validates :type, type: :string, presence: true
       validates :event_types, type: :array, presence: true, items: [{ type: :string, presence: true }]
 
+      # Initializes a new Webhook object.
+      #
+      # @param url [String] the URL where the webhook will send data.
+      # @param type [String] the type of webhook.
+      # @param event_types [Array<String>] the list of event types for the webhook.
+      # @raise [ArgumentError] if any attribute validation fails.
       def initialize(url:, type:, event_types:)
         @url = url
         @type = type
@@ -20,6 +28,9 @@ module CDEKApiClient
         validate!
       end
 
+      # Converts the Webhook object to a JSON representation.
+      #
+      # @return [String] the JSON representation of the Webhook.
       def to_json(*_args)
         {
           url: @url,

data/lib/cdek_api_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CDEKApiClient
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/cdek_api_client.rb

@@ -1,36 +1,64 @@
 # frozen_string_literal: true
 
+require_relative 'cdek_api_client/api/location'
+require_relative 'cdek_api_client/api/order'
+require_relative 'cdek_api_client/api/tariff'
+require_relative 'cdek_api_client/api/track_order'
+require_relative 'cdek_api_client/api/webhook'
 require_relative 'cdek_api_client/client'
-require_relative 'cdek_api_client/order'
-require_relative 'cdek_api_client/track_order'
-require_relative 'cdek_api_client/tariff'
-require_relative 'cdek_api_client/version'
-require_relative 'cdek_api_client/location'
-require_relative 'cdek_api_client/webhook'
-require_relative 'cdek_api_client/entities/order_data'
+require_relative 'cdek_api_client/entities/currency_mapper'
+require_relative 'cdek_api_client/entities/item'
 require_relative 'cdek_api_client/entities/location'
+require_relative 'cdek_api_client/entities/order_data'
 require_relative 'cdek_api_client/entities/package'
+require_relative 'cdek_api_client/entities/payment'
 require_relative 'cdek_api_client/entities/recipient'
-require_relative 'cdek_api_client/entities/item'
-require_relative 'cdek_api_client/entities/validatable'
 require_relative 'cdek_api_client/entities/sender'
-require_relative 'cdek_api_client/entities/currency_mapper'
-require_relative 'cdek_api_client/entities/tariff_data'
-require_relative 'cdek_api_client/entities/payment'
 require_relative 'cdek_api_client/entities/service'
+require_relative 'cdek_api_client/entities/tariff_data'
+require_relative 'cdek_api_client/entities/validatable'
 require_relative 'cdek_api_client/entities/webhook'
+require_relative 'cdek_api_client/version'
+
+# frozen_string_literal: true
 
+# CDEKApiClient is a Ruby client for interacting with the CDEK API.
+# It provides functionalities for order creation, tracking, tariff calculation,
+# location data retrieval, and webhook management. This gem ensures clean,
+# robust, and maintainable code with proper validations.
+#
+# To use this gem, configure it with your CDEK API client ID and secret,
+# and then access various API functionalities through the provided client.
+#
+# Example:
+#   CDEKApiClient.configure do |config|
+#     config.client_id = 'your_client_id'
+#     config.client_secret = 'your_client_secret'
+#   end
+#   client = CDEKApiClient.client
+#
+# For more details, refer to the README.
 module CDEKApiClient
   class Error < StandardError; end
 
   class << self
+    # Configures the client with the provided block.
+    # @yield [self] Yields the client to the provided block.
     def configure
       yield self
     end
 
-    attr_accessor :client_id, :client_secret
+    # @!attribute [rw] client_id
+    #   @return [String] The client ID for authentication.
+    attr_accessor :client_id
+
+    # @!attribute [rw] client_secret
+    #   @return [String] The client secret for authentication.
+    attr_accessor :client_secret
   end
 
+  # Returns the CDEK API client.
+  # @return [CDEKApiClient::Client] The CDEK API client instance.
   def self.client
     @client ||= CDEKApiClient::Client.new(client_id, client_secret)
   end

metadata

@@ -1,57 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: cdek_api_client
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Damir Mukimov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-07-20 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: base64
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.2.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.2.0
-- !ruby/object:Gem::Dependency
-  name: faraday
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.10.3
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.10.3
-- !ruby/object:Gem::Dependency
-  name: faraday_middleware
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.2.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.2.0
+date: 2024-07-22 00:00:00.000000000 Z
+dependencies: []
 description: This gem provides a Ruby client for interacting with the CDEK API, including
   order creation, tracking, and tariff calculation.
 email:
@@ -62,6 +20,11 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/cdek_api_client.rb
+- lib/cdek_api_client/api/location.rb
+- lib/cdek_api_client/api/order.rb
+- lib/cdek_api_client/api/tariff.rb
+- lib/cdek_api_client/api/track_order.rb
+- lib/cdek_api_client/api/webhook.rb
 - lib/cdek_api_client/client.rb
 - lib/cdek_api_client/entities/currency_mapper.rb
 - lib/cdek_api_client/entities/item.rb
@@ -75,13 +38,7 @@ files:
 - lib/cdek_api_client/entities/tariff_data.rb
 - lib/cdek_api_client/entities/validatable.rb
 - lib/cdek_api_client/entities/webhook.rb
-- lib/cdek_api_client/location.rb
-- lib/cdek_api_client/order.rb
-- lib/cdek_api_client/recipient.rb
-- lib/cdek_api_client/tariff.rb
-- lib/cdek_api_client/track_order.rb
 - lib/cdek_api_client/version.rb
-- lib/cdek_api_client/webhook.rb
 homepage: http://glowing-pixels.com/cdek_api_client
 licenses:
 - MIT

data/lib/cdek_api_client/location.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module CDEKApiClient
-  class Location
-    CITIES_URL = 'location/cities'
-    REGIONS_URL = 'location/regions'
-
-    def initialize(client)
-      @client = client
-    end
-
-    def cities
-      response = @client.auth_connection.get(CITIES_URL) do |req|
-        req.headers['Content-Type'] = 'application/json'
-      end
-      handle_response(response)
-    end
-
-    def regions
-      response = @client.auth_connection.get(REGIONS_URL) do |req|
-        req.headers['Content-Type'] = 'application/json'
-      end
-      handle_response(response)
-    end
-
-    private
-
-    def handle_response(response)
-      @client.send(:handle_response, response)
-    end
-  end
-end