cdek_api_client 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 389563fd9ba0f235cdc75afdc77906d9e2fb7d3f6da3d4392105758c8ad8756a
-  data.tar.gz: dfa1b6d50ea42547dfdf8c5846a47c9882e8b2ab5f56557b014d122a026c5eb2
+  metadata.gz: fb260a05ab2e01a502a9170810e6f4ad293f4250d369aa78495346ee91b41f42
+  data.tar.gz: 1072390e4220defd519199194b301a166caade65276204ceec4314d98e738562
 SHA512:
-  metadata.gz: 364b5510d3f833a43ff3ab1d0581844821e1cbce1211a61b81802c3fb1f228d901621552c57e4052aaa88ae6609861ee5a2e1ff6ad759eaa970d51b70de1b3a5
-  data.tar.gz: b982eef2e9d6bb5f268204af574605f7f96a077331cfeb38d58db02a2ef9be601e5cac83439b4aa879b245ac41262c97a3dcb6cc83eca2bf977e5359af989089
+  metadata.gz: d1bdbca95336d4c39bb72909e880aa8473b2a0249ccc997a504916c55944b8fe750454e1c5bd171eacfe45c47f9dc3a3b92743957a898102c39d90c8ff88ef7a
+  data.tar.gz: e0f39d6d3ccb456f98446974e96c1160a001fc6c9970fc9e2162efcc24cdd78aa003e2516d6256ce4de9add37634c83b3d9c7e7a125bc34fbd9a668c9647591f

data/README.md

@@ -2,12 +2,24 @@
 
 [![Gem Version](https://badge.fury.io/rb/cdek_api_client.svg)](https://badge.fury.io/rb/cdek_api_client)
 
-A Ruby client for interacting with the CDEK API, providing functionalities for order creation, tracking, tariff calculation, location data retrieval, and webhook management. This gem ensures clean, robust, and maintainable code with proper validations.
+### Other Languages
 
-This Readme is also available in:
+- [Русский](README_RUS.md)
+- [Татарча](README_TAT.md)
+- [English](README.md)
 
-- [Russian](README_RUS.md)
-- [Tatar](README_TAT.md)
+**Important:** This gem is in the early stages of development and it is shared as it is. Any support for development or feedback is welcome; please check the [Contributing](#contributing) section for more information.
+
+## Overview
+
+CDEK ([СДЭК](https://www.cdek.ru/)) is a big logistics company in Russia, that provides a wide range of delivery services for businesses and individuals. The [CDEK API](https://www.cdek.ru/ru/integration/api) allows developers to integrate CDEK's services into their applications, enabling functionalities such as order creation, tracking, tariff calculation, location data retrieval, and webhook management.
+
+The `cdek_api_client` gem offers a clean and robust interface to interact with the CDEK API, ensuring maintainable code with proper validations. This gem supports the following features:
+
+- Creating and tracking orders
+- Calculating tariffs
+- Retrieving location data (cities, regions, postal codes, and offices)
+- Managing webhooks
 
 ## Table of Contents
 
@@ -19,12 +31,15 @@ This Readme is also available in:
   - [Calculating Tariff](#calculating-tariff)
   - [Getting Location Data](#getting-location-data)
   - [Setting Up Webhooks](#setting-up-webhooks)
+  - [Fetching and Saving Location Data](#fetching-and-saving-location-data)
 - [Entities](#entities)
   - [OrderData](#orderdata)
   - [Recipient](#recipient)
   - [Sender](#sender)
   - [Package](#package)
   - [Item](#item)
+- [TODO List](#todo-list)
+- [Changelog](#changelog)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -36,8 +51,6 @@ Add this line to your application's Gemfile:
 gem 'cdek_api_client'
 ```
 
-````
-
 And then execute:
 
 ```sh
@@ -222,7 +235,44 @@ rescue => e
 end
 ```
 
-## Entities
+### Fetching Location Data
+
+The gem has pre-cached values and uses them by default. Users can override this behavior by fetching live data.
+
+You can fetch cities, regions, offices, and postal code data directly from CDEK API.
+
+```ruby
+
+# Fetching cities
+begin
+  cities = location_client.cities(use_live_data: true)
+rescue => e
+  puts "Error fetching cities: #{e.message}"
+end
+
+# Fetching regions
+begin
+  regions = location_client.regions(use_live_data: true)
+rescue => e
+  puts "Error fetching regions: #{e.message}"
+end
+
+# Fetching  offices
+begin
+  offices = location_client.offices(use_live_data: true)
+rescue => e
+  puts "Error fetching offices: #{e.message}"
+end
+
+# Fetching postal codes for each city
+begin
+  cities = location_client.cities(use_live_data: true)
+rescue => e
+  puts "Error fetching postal codes: #{e.message}"
+end
+```
+
+### Entities
 
 ### OrderData
 
@@ -237,7 +287,7 @@ Attributes:
 - `recipient` (Recipient, required): The recipient details.
 - `sender` (Sender, required): The sender details.
 - `from_location` (Hash, required): The location details from where the order is shipped.
-- `to_location` (Hash, required): The location details to where the order is shipped.
+- `to_location` (Hash, required): The location details of where the order is shipped.
 - `services` (Array): Additional services.
 - `packages` (Array, required): List of packages.
 
@@ -253,7 +303,7 @@ Attributes:
 
 ### Sender
 
-Represents the sender details.
+Represents the sender's details.
 
 Attributes:
 
@@ -290,17 +340,25 @@ Attributes:
 
 ## TODO List
 
-- [ ] Restructure the codebase for better organization.
-- [ ] Add mappings for CDEK internal codes.
+- [x] Restructure the codebase for better organization.
+- [x] Add mappings for CDEK internal codes.
 - [ ] Add more API endpoints and data entities.
 - [ ] Check all attributes for required and optional fields.
 - [ ] Add documentation for all classes and methods.
 
+## Changelog
+
+### v0.2.0
+
+- **Added**: Improved error handling and response parsing in `Client`.
+- **Updated**: Code structure for better organization.
+- **Updated**: Specs for `Client` and `API` classes.
+- **Updated**: `README.md` with detailed usage examples, including fetching and saving location data with optional live data fetching.
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at [https://github.com/your-username/cdek_api_client](https://github.com/your-username/cdek_api_client).
+Bug reports and pull requests are welcome on GitHub. This gem is used in a couple of projects and fulfills the requirements of those projects. If you have any suggestions or improvements, feel free to open an issue or a pull request.
 
 ## License
 
-The gem is available as open-source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-````
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/cdek_api_client/api/location.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module CDEKApiClient
+  module API
+    # Handles location-related API requests.
+    class Location
+      # Initializes the Location object.
+      #
+      # @param client [CDEKApiClient::Client] the client instance.
+      def initialize(client)
+        @client = client
+      end
+
+      # Retrieves a list of cities.
+      #
+      # @param use_live_data [Boolean] whether to use live data or cached data.
+      # @return [Array<Hash>] list of cities.
+      def cities(use_live_data: false)
+        use_live_data ? @client.request('get', 'location/cities') : read_data_from_file('cities_mapping.json')
+      end
+
+      # Retrieves a list of regions.
+      #
+      # @param use_live_data [Boolean] whether to use live data or cached data.
+      # @return [Array<Hash>] list of regions.
+      def regions(use_live_data: false)
+        use_live_data ? @client.request('get', 'location/regions') : read_data_from_file('regions_mapping.json')
+      end
+
+      # Retrieves a list of offices.
+      #
+      # @param use_live_data [Boolean] whether to use live data or cached data.
+      # @return [Array<Hash>] list of offices.
+      def offices(use_live_data: false)
+        use_live_data ? @client.request('get', 'deliverypoints') : read_data_from_file('offices_mapping.json')
+      end
+
+      # Retrieves a list of postal codes.
+      #
+      # @param city_code [String, nil] the city code to filter postal codes.
+      # @param use_live_data [Boolean] whether to use live data or cached data.
+      # @return [Array<Hash>] list of postal codes.
+      def postal_codes(city_code = nil, use_live_data: false)
+        if use_live_data
+          if city_code
+            @client.request('get',
+                            "location/postalcodes?code=#{city_code}")
+          else
+            @client.request('get',
+                            'location/postalcodes')
+          end
+        else
+          read_data_from_file('postal_codes_mapping.json')
+        end
+      end
+
+      private
+
+      # Reads data from a file.
+      #
+      # @param filename [String] the name of the file to read.
+      # @return [Hash] the parsed JSON data from the file.
+      def read_data_from_file(filename)
+        file_path = File.join('data', filename)
+        JSON.parse(File.read(file_path))
+      rescue StandardError => e
+        @client.logger.error("Failed to read data from file: #{e.message}")
+        { 'error' => e.message }
+      end
+    end
+  end
+end

data/lib/cdek_api_client/api/order.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module CDEKApiClient
+  module API
+    # Handles order-related API requests.
+    class Order
+      # Initializes the Order object.
+      #
+      # @param client [CDEKApiClient::Client] the client instance.
+      def initialize(client)
+        @client = client
+      end
+
+      # Creates a new order.
+      #
+      # @param order_data [CDEKApiClient::Entities::OrderData] the data for the order.
+      # @return [Hash] the response from the API.
+      def create(order_data)
+        response = @client.request('post', 'orders', body: order_data)
+        handle_response(response)
+      end
+
+      # Tracks an order by its UUID.
+      #
+      # @param order_uuid [String] the UUID of the order.
+      # @return [Hash] the tracking information.
+      def track(order_uuid)
+        response = @client.request('get', "orders/#{order_uuid}")
+        handle_response(response)
+      end
+
+      private
+
+      # Handles the response from the API.
+      #
+      # @param response [Net::HTTPResponse] the response from the API.
+      # @return [Hash] the parsed response.
+      def handle_response(response)
+        @client.send(:handle_response, response)
+      end
+    end
+  end
+end

data/lib/cdek_api_client/api/tariff.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CDEKApiClient
+  module API
+    # Handles tariff-related API requests.
+    class Tariff
+      # Initializes the Tariff object.
+      #
+      # @param client [CDEKApiClient::Client] the client instance.
+      def initialize(client)
+        @client = client
+      end
+
+      # Calculates the tariff.
+      #
+      # @param tariff_data [CDEKApiClient::Entities::TariffData] the data for the tariff calculation.
+      # @return [Hash] the response from the API.
+      def calculate(tariff_data)
+        @client.request('post', 'calculator/tariff', body: tariff_data)
+      end
+    end
+  end
+end

data/lib/cdek_api_client/api/track_order.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module CDEKApiClient
+  module API
+    # Handles order tracking requests to the CDEK API.
+    class TrackOrder
+      BASE_URL = ENV.fetch('CDEK_API_URL', 'https://api.edu.cdek.ru/v2')
+      TRACK_ORDER_URL = "#{BASE_URL}/orders/%<uuid>s".freeze
+
+      # Initializes the TrackOrder object.
+      #
+      # @param client [CDEKApiClient::Client] the client instance.
+      def initialize(client)
+        @client = client
+      end
+
+      # Retrieves tracking information for an order.
+      #
+      # @param order_uuid [String] the UUID of the order.
+      # @return [Hash] the tracking information.
+      # @raise [ArgumentError] if the UUID is invalid.
+      def get(order_uuid)
+        validate_uuid(order_uuid)
+
+        response = @client.auth_connection.get(format(TRACK_ORDER_URL, uuid: order_uuid))
+        handle_response(response)
+      end
+
+      private
+
+      # Validates the order UUID.
+      #
+      # @param uuid [String] the UUID to validate.
+      # @raise [ArgumentError] if the UUID is invalid.
+      def validate_uuid(uuid)
+        @client.send(:validate_uuid, uuid)
+      end
+
+      # Handles the response from the API.
+      #
+      # @param response [Net::HTTPResponse] the response from the API.
+      # @return [Hash] the parsed response.
+      def handle_response(response)
+        @client.send(:handle_response, response)
+      end
+    end
+  end
+end

data/lib/cdek_api_client/api/webhook.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module CDEKApiClient
+  module API
+    # Handles webhook-related API requests.
+    class Webhook
+      # Initializes the Webhook object.
+      #
+      # @param client [CDEKApiClient::Client] the client instance.
+      def initialize(client)
+        @client = client
+      end
+
+      # Registers a new webhook.
+      #
+      # @param webhook_data [CDEKApiClient::Entities::Webhook] the data for the webhook.
+      # @return [Hash] the response from the API.
+      def register(webhook_data)
+        response = @client.request('post', 'webhooks', body: webhook_data)
+        @client.send(:handle_response, response)
+      end
+
+      # Retrieves a list of registered webhooks.
+      #
+      # @return [Array<Hash>] the list of webhooks.
+      def list
+        response = @client.request('get', 'webhooks')
+        @client.send(:handle_response, response)
+      end
+
+      # Deletes a webhook by its ID.
+      #
+      # @param webhook_id [String] the ID of the webhook to delete.
+      # @return [Hash] the response from the API.
+      def delete(webhook_id)
+        response = @client.request('delete', "webhooks/#{webhook_id}")
+        @client.send(:handle_response, response)
+      end
+    end
+  end
+end

data/lib/cdek_api_client/client.rb

@@ -1,114 +1,141 @@
 # frozen_string_literal: true
 
-require 'faraday'
-require 'faraday_middleware'
+require 'net/http'
+require 'uri'
 require 'json'
 require 'logger'
+require_relative 'api/location'
+require_relative 'api/order'
+require_relative 'api/tariff'
+require_relative 'api/webhook'
 
 module CDEKApiClient
-  ##
   # Client class for interacting with the CDEK API.
-  #
-  # This class provides methods for authentication and initializing the API resources
-  # for orders, locations, tariffs, and webhooks.
-  #
-  # @attr_reader [String] token The access token used for authentication.
-  # @attr_reader [Logger] logger The logger used for logging HTTP requests and responses.
-  # @attr_reader [Order] order The Order resource for interacting with order-related API endpoints.
-  # @attr_reader [Location] location The Location resource for interacting with location-related API endpoints.
-  # @attr_reader [Tariff] tariff The Tariff resource for interacting with tariff-related API endpoints.
-  # @attr_reader [Webhook] webhook The Webhook resource for interacting with webhook-related API endpoints.
   class Client
     BASE_URL = ENV.fetch('CDEK_API_URL', 'https://api.edu.cdek.ru/v2')
     TOKEN_URL = "#{BASE_URL}/oauth/token".freeze
 
-    attr_reader :token, :logger, :order, :location, :tariff, :webhook
+    # @return [String] the access token for API authentication.
+    attr_reader :token
+    # @return [Logger] the logger instance.
+    attr_reader :logger
+    # @return [CDEKApiClient::Order] the order API interface.
+    attr_reader :order
+    # @return [CDEKApiClient::Location] the location API interface.
+    attr_reader :location
+    # @return [CDEKApiClient::Tariff] the tariff API interface.
+    attr_reader :tariff
+    # @return [CDEKApiClient::Webhook] the webhook API interface.
+    attr_reader :webhook
 
-    ##
-    # Initializes a new Client object.
+    # Initializes the client with API credentials and logger.
     #
-    # @param [String] client_id The client ID for authentication.
-    # @param [String] client_secret The client secret for authentication.
-    # @param [Logger] logger The logger for logging HTTP requests and responses.
+    # @param client_id [String] the client ID.
+    # @param client_secret [String] the client secret.
+    # @param logger [Logger] the logger instance.
     def initialize(client_id, client_secret, logger: Logger.new($stdout))
       @client_id = client_id
       @client_secret = client_secret
       @logger = logger
       @token = authenticate
 
-      @order = CDEKApiClient::Order.new(self)
-      @location = CDEKApiClient::Location.new(self)
-      @tariff = CDEKApiClient::Tariff.new(self)
-      @webhook = CDEKApiClient::Webhook.new(self)
+      @order = CDEKApiClient::API::Order.new(self)
+      @location = CDEKApiClient::API::Location.new(self)
+      @tariff = CDEKApiClient::API::Tariff.new(self)
+      @webhook = CDEKApiClient::API::Webhook.new(self)
     end
 
-    ##
-    # Authenticates with the CDEK API and retrieves an access token.
+    # Authenticates with the API and retrieves an access token.
     #
-    # @return [String] The access token.
-    # @raise [Error] if there is an error getting the token.
+    # @return [String] the access token.
+    # @raise [StandardError] if authentication fails.
     def authenticate
-      response = connection.post(TOKEN_URL) do |req|
-        req.body = {
-          grant_type: 'client_credentials',
-          client_id: @client_id,
-          client_secret: @client_secret
-        }
-      end
+      uri = URI(TOKEN_URL)
+      response = Net::HTTP.post_form(uri, {
+                                       grant_type: 'client_credentials',
+                                       client_id: @client_id,
+                                       client_secret: @client_secret
+                                     })
 
-      raise Error, "Error getting token: #{response.body}" unless response.success?
+      raise "Error getting token: #{response.body}" unless response.is_a?(Net::HTTPSuccess)
 
-      response.body['access_token']
+      JSON.parse(response.body)['access_token']
     end
 
-    ##
-    # Creates a Faraday connection object.
+    # Makes an HTTP request to the API.
     #
-    # @return [Faraday::Connection] The Faraday connection object.
-    def connection
-      Faraday.new(url: BASE_URL) do |conn|
-        conn.request :url_encoded
-        conn.response :json, content_type: /\bjson$/
-        conn.adapter Faraday.default_adapter
-        conn.response :logger, @logger, bodies: true
-      end
+    # @param method [String] the HTTP method (e.g., 'get', 'post').
+    # @param path [String] the API endpoint path.
+    # @param body [Hash, nil] the request body.
+    # @return [Hash, Array] the parsed response.
+    def request(method, path, body: nil)
+      uri = URI("#{BASE_URL}/#{path}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      request = build_request(method, uri, body)
+      response = http.request(request)
+      handle_response(response)
+    rescue StandardError => e
+      @logger.error("HTTP request failed: #{e.message}")
+      { 'error' => e.message }
     end
 
-    ##
-    # Creates a Faraday connection object with authorization.
+    private
+
+    # Builds an HTTP request with the specified method, URI, and body.
     #
-    # @return [Faraday::Connection] The Faraday connection object with authorization.
-    def auth_connection
-      Faraday.new(url: BASE_URL) do |conn|
-        conn.request :url_encoded
-        conn.response :json, content_type: /\bjson$/
-        conn.authorization :Bearer, @token
-        conn.adapter Faraday.default_adapter
-        conn.response :logger, @logger, bodies: true
-      end
+    # @param method [String] the HTTP method (e.g., 'get', 'post').
+    # @param uri [URI::HTTP] the URI for the request.
+    # @param body [Hash, nil] the request body.
+    # @return [Net::HTTPRequest] the constructed HTTP request.
+    def build_request(method, uri, body)
+      request_class = Net::HTTP.const_get(method.capitalize)
+      request = request_class.new(uri.request_uri)
+      request['Authorization'] = "Bearer #{@token}"
+      request['Content-Type'] = 'application/json'
+      request.body = body.to_json if body
+      request
     end
 
-    ##
-    # Handles the response from the API.
+    # Handles the API response, parsing JSON and handling errors.
     #
-    # @param [Faraday::Response] response The response object.
-    # @return [Hash] The parsed response body.
-    # @raise [Error] if the response is not successful.
+    # @param response [Net::HTTPResponse] the HTTP response.
+    # @return [Hash, Array] the parsed response.
     def handle_response(response)
-      raise Error, "Error: #{response.body}" unless response.success?
+      case response
+      when Net::HTTPSuccess
+        parsed_response = parse_json(response.body)
+        return parsed_response unless parsed_response.is_a?(Hash) && parsed_response.key?('error')
 
-      response.body
+        log_error("API Error: #{parsed_response['error']}")
+        { 'error' => parsed_response['error'] }
+      when Array, Hash
+        response
+      else
+        log_error("Unexpected response type: #{response.class}")
+        { 'error' => "Unexpected response type: #{response.class}" }
+      end
+    rescue JSON::ParserError => e
+      log_error("Failed to parse response: #{e.message}")
+      { 'error' => "Failed to parse response: #{e.message}" }
     end
 
-    ##
-    # Validates the format of a UUID.
+    # Parses a JSON string, handling any parsing errors.
     #
-    # @param [String] uuid The UUID to validate.
-    # @raise [RuntimeError] if the UUID format is invalid.
-    def validate_uuid(uuid)
-      return if uuid.match?(/\A[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\z/)
+    # @param body [String] the JSON string to parse.
+    # @return [Hash] the parsed JSON.
+    def parse_json(body)
+      JSON.parse(body)
+    rescue JSON::ParserError => e
+      log_error("Failed to parse JSON body: #{e.message}")
+      { 'error' => "Failed to parse JSON body: #{e.message}" }
+    end
 
-      raise 'Invalid UUID format'
+    # Logs an error message.
+    #
+    # @param message [String] the error message to log.
+    def log_error(message)
+      @logger.error(message)
     end
   end
 end

data/lib/cdek_api_client/entities/currency_mapper.rb

@@ -2,6 +2,7 @@
 
 module CDEKApiClient
   module Entities
+    # CurrencyMapper is a utility module that maps currency codes to their respective integer representations.
     module CurrencyMapper
       CURRENCY_CODES = {
         'RUB' => 1,
@@ -26,6 +27,11 @@ module CDEKApiClient
         'JPY' => 55
       }.freeze
 
+      # Converts a currency code to its corresponding integer representation.
+      #
+      # @param currency [String] the currency code to convert.
+      # @return [Integer] the integer representation of the currency code.
+      # @raise [ArgumentError] if the currency code is invalid.
       def self.to_code(currency)
         CURRENCY_CODES[currency] || (raise ArgumentError, "Invalid currency code: #{currency}")
       end

data/lib/cdek_api_client/entities/item.rb

@@ -5,6 +5,8 @@ require_relative 'payment'
 
 module CDEKApiClient
   module Entities
+    # Represents an item in the CDEK API.
+    # Each item has attributes such as ware key, payment, name, cost, amount, weight, and optional URL.
     class Item
       include Validatable
 
@@ -17,6 +19,16 @@ module CDEKApiClient
       validates :amount, type: :integer, presence: true
       validates :weight, type: :integer, presence: true
 
+      # Initializes a new Item object.
+      #
+      # @param ware_key [String] the ware key of the item.
+      # @param payment [Payment] the payment details of the item.
+      # @param name [String] the name of the item.
+      # @param cost [Integer] the cost of the item.
+      # @param amount [Integer] the amount of the item.
+      # @param weight [Integer] the weight of the item.
+      # @param url [String, nil] the optional URL of the item.
+      # @raise [ArgumentError] if any attribute validation fails.
       def initialize(ware_key:, payment:, name:, cost:, amount:, weight:, url: nil)
         @ware_key = ware_key
         @payment = payment
@@ -28,6 +40,9 @@ module CDEKApiClient
         validate!
       end
 
+      # Converts the Item object to a JSON representation.
+      #
+      # @return [String] the JSON representation of the Item.
       def to_json(*_args)
         {
           ware_key: @ware_key,