belpost 0.1.0

data/lib/belpost/client.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "api_service"
+require_relative "models/parcel"
+require_relative "models/api_response"
+
+module Belpost
+  # Main client class for interacting with the BelPost API.
+  class Client
+    # Initializes a new instance of the Client.
+    #
+    # @raise [Belpost::Error] If JWT token is not configured.
+    def initialize(logger: Logger.new($stdout))
+      @config = Belpost.configuration
+      raise ConfigurationError, "JWT token is required" if @config.jwt_token.nil?
+
+      @api_service = ApiService.new(
+        base_url: @config.base_url,
+        jwt_token: @config.jwt_token,
+        timeout: @config.timeout,
+        logger: logger
+      )
+    end
+
+    # Creates a new postal parcel by sending a POST request to the API.
+    #
+    # @param parcel_data [Hash] The data for the postal parcel.
+    # @return [Hash] The parsed JSON response from the API.
+    # @raise [Belpost::InvalidRequestError] If the request data is invalid.
+    # @raise [Belpost::ApiError] If the API returns an error response.
+    def create_parcel(parcel_data)
+      validation_result = Validation::ParcelSchema.call(parcel_data)
+      unless validation_result.success?
+        raise ValidationError, "Invalid parcel data: #{validation_result.errors.to_h}"
+      end
+
+      parcel = Models::Parcel.new(parcel_data)
+      response = @api_service.post("/api/v1/business/postal-deliveries", parcel.to_h)
+      response.to_h
+    end
+
+    # Fetches the HS codes tree from the API.
+    #
+    # @return [Array<Hash>] The HS codes tree as an array of hashes.
+    # @raise [Belpost::ApiError] If the API returns an error response.
+    def fetch_hs_codes
+      response = @api_service.get("/api/v1/business/postal-deliveries/hs-codes/list")
+      response.to_h
+    end
+
+    # Fetches validation data for postal deliveries based on the country code.
+    #
+    # @param country_code [String] The country code (e.g. "BY", "RU-LEN").
+    # @return [Hash] The parsed JSON response containing validation data.
+    # @raise [Belpost::ApiError] If the API returns an error response.
+    def validate_postal_delivery(country_code)
+      country_code = country_code.upcase
+      response = @api_service.get("/api/v1/business/postal-deliveries/validation/#{country_code}")
+      response.to_h
+    end
+
+    # Allows you to get a list of countries to which postal items are sent.
+    #
+    # @return [Hash] The parsed JSON response containing available countries.
+    # @raise [Belpost::ApiError] If the API returns an error response.
+    def fetch_available_countries
+      response = @api_service.get("/api/v1/business/postal-deliveries/countries")
+      response.to_h
+    end
+  end
+end

data/lib/belpost/configuration.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Belpost
+  # Class for managing the Belpochta API configuration.
+  # Allows you to set basic parameters such as API URL, JWT token, and request timeout.
+  class Configuration
+    attr_accessor :base_url, :jwt_token, :timeout
+
+    def initialize
+      @base_url = ENV.fetch("BELPOST_API_URL")
+      @jwt_token = ENV.fetch("BELPOST_JWT_TOKEN", nil)
+      @timeout = ENV.fetch("BELPOST_TIMEOUT", 10).to_i
+    end
+  end
+end

data/lib/belpost/errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Belpost
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class ApiError < Error
+    attr_reader :status_code, :response_body
+
+    def initialize(message, status_code: nil, response_body: nil)
+      @status_code = status_code
+      @response_body = response_body
+      super(message)
+    end
+  end
+
+  class AuthenticationError < ApiError; end
+  class InvalidRequestError < ApiError; end
+  class RateLimitError < ApiError; end
+  class ServerError < ApiError; end
+  class NetworkError < Error; end
+  class TimeoutError < Error; end
+  class ValidationError < Error; end
+  class RequestError < Error; end
+  class ParseError < Error; end
+end

data/lib/belpost/models/api_response.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Belpost
+  module Models
+    class ApiResponse
+      attr_reader :data, :status_code, :headers
+
+      def initialize(data:, status_code:, headers:)
+        @data = data
+        @status_code = status_code
+        @headers = headers
+      end
+
+      def success?
+        status_code == 200
+      end
+
+      def to_h
+        data
+      end
+    end
+  end
+end 

data/lib/belpost/models/customs_declaration.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Belpost
+  module Models
+    class CustomsDeclaration
+      VALID_CATEGORIES = %w[gift documents sample returned_goods merchandise other].freeze
+
+      attr_reader :items, :price, :category, :explanation, :comments, :invoice, :licences, :certificates
+
+      def initialize(data = {})
+        @items = data[:items] || []
+        @price = data[:price] || {}
+        @category = data[:category]
+        @explanation = data[:explanation]
+        @comments = data[:comments]
+        @invoice = data[:invoice]
+        @licences = data[:licences] || []
+        @certificates = data[:certificates] || []
+      end
+
+      def add_item(item_data)
+        @items << item_data
+      end
+
+      def set_price(currency, value)
+        @price = { currency: currency, value: value }
+      end
+
+      def set_category(category)
+        unless VALID_CATEGORIES.include?(category)
+          raise ValidationError, "Invalid category. Must be one of: #{VALID_CATEGORIES.join(', ')}"
+        end
+
+        @category = category
+      end
+
+      def to_h
+        {
+          items: @items,
+          price: @price,
+          category: @category,
+          explanation: @explanation,
+          comments: @comments,
+          invoice: @invoice,
+          licences: @licences,
+          certificates: @certificates
+        }.compact
+      end
+
+      def valid?
+        return false if @category && !VALID_CATEGORIES.include?(@category)
+        return false if @category == "other" && @explanation.nil?
+        
+        # Проверка наличия обязательных полей для коммерческих отправлений
+        if %w[merchandise sample returned_goods].include?(@category)
+          return false if @items.empty?
+          return false if @price.empty?
+        end
+
+        true
+      end
+    end
+  end
+end 

data/lib/belpost/models/parcel.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Belpost
+  module Models
+    class Parcel
+      attr_reader :data
+
+      def initialize(data)
+        @data = data
+      end
+
+      def to_h
+        data
+      end
+
+      def to_json(*_args)
+        data.to_json
+      end
+    end
+  end
+end

data/lib/belpost/models/parcel_builder.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module Belpost
+  module Models
+    class ParcelBuilder
+      def initialize
+        @data = {
+          parcel: {
+            type: "package",
+            attachment_type: "products",
+            measures: {},
+            departure: {
+              country: "BY",
+              place: "post_office"
+            },
+            arrival: {
+              place: "post_office"
+            }
+          },
+          addons: {},
+          sender: {
+            info: {},
+            location: {}
+          },
+          recipient: {
+            info: {},
+            location: {}
+          }
+        }
+      end
+
+      # Основные параметры посылки
+      def with_type(type)
+        @data[:parcel][:type] = type
+        self
+      end
+
+      def with_attachment_type(attachment_type)
+        @data[:parcel][:attachment_type] = attachment_type
+        self
+      end
+
+      def with_weight(weight_in_grams)
+        @data[:parcel][:measures][:weight] = weight_in_grams
+        self
+      end
+
+      def with_dimensions(length, width, height)
+        @data[:parcel][:measures][:long] = length
+        @data[:parcel][:measures][:width] = width
+        @data[:parcel][:measures][:height] = height
+        self
+      end
+
+      def to_country(country_code)
+        @data[:parcel][:arrival][:country] = country_code
+        self
+      end
+
+      # Дополнительные сервисы
+      def with_declared_value(value, currency = "BYN")
+        @data[:addons][:declared_value] = {
+          currency: currency,
+          value: value.to_f
+        }
+        self
+      end
+
+      def with_cash_on_delivery(value, currency = "BYN")
+        @data[:addons][:cash_on_delivery] = {
+          currency: currency,
+          value: value.to_f
+        }
+        self
+      end
+
+      def add_service(service_name, value = true)
+        @data[:addons][service_name.to_sym] = value
+        self
+      end
+
+      # Отправитель
+      def from_legal_person(organization_name)
+        @data[:sender][:type] = "legal_person"
+        @data[:sender][:info][:organization_name] = organization_name
+        self
+      end
+
+      def from_sole_proprietor(organization_name)
+        @data[:sender][:type] = "sole_proprietor"
+        @data[:sender][:info][:organization_name] = organization_name
+        self
+      end
+
+      def with_sender_details(taxpayer_number: nil, bank: nil, iban: nil, bic: nil)
+        @data[:sender][:info][:taxpayer_number] = taxpayer_number if taxpayer_number
+        @data[:sender][:info][:bank] = bank if bank
+        @data[:sender][:info][:IBAN] = iban if iban
+        @data[:sender][:info][:BIC] = bic if bic
+        self
+      end
+
+      def with_sender_location(postal_code:, region:, district:, locality_type:, locality_name:, road_type:, road_name:, building:, housing: nil, apartment: nil)
+        @data[:sender][:location] = {
+          code: postal_code,
+          region: region,
+          district: district,
+          locality: {
+            type: locality_type,
+            name: locality_name
+          },
+          road: {
+            type: road_type,
+            name: road_name
+          },
+          building: building,
+          housing: housing,
+          apartment: apartment
+        }.compact
+        self
+      end
+
+      def with_sender_contact(email:, phone:)
+        @data[:sender][:email] = email
+        @data[:sender][:phone] = phone
+        self
+      end
+
+      # Получатель
+      def to_natural_person(first_name:, last_name:, second_name: nil)
+        @data[:recipient][:type] = "natural_person"
+        @data[:recipient][:info] = {
+          first_name: first_name,
+          last_name: last_name,
+          second_name: second_name
+        }.compact
+        self
+      end
+
+      def to_legal_person(organization_name)
+        @data[:recipient][:type] = "legal_person"
+        @data[:recipient][:info] = {
+          organization_name: organization_name
+        }
+        self
+      end
+
+      def with_recipient_location(postal_code:, region:, district:, locality_type:, locality_name:, road_type:, road_name:, building:, housing: nil, apartment: nil)
+        @data[:recipient][:location] = {
+          code: postal_code,
+          region: region,
+          district: district,
+          locality: {
+            type: locality_type,
+            name: locality_name
+          },
+          road: {
+            type: road_type,
+            name: road_name
+          },
+          building: building,
+          housing: housing,
+          apartment: apartment
+        }.compact
+        self
+      end
+
+      def with_foreign_recipient_location(postal_code:, locality:, address:)
+        @data[:recipient][:location] = {
+          code: postal_code,
+          locality: locality,
+          address: address
+        }
+        self
+      end
+
+      def with_recipient_contact(email: nil, phone:)
+        @data[:recipient][:email] = email
+        @data[:recipient][:phone] = phone
+        self
+      end
+
+      # Таможенная декларация
+      def with_customs_declaration(customs_declaration)
+        @data[:cp72] = customs_declaration.to_h
+        self
+      end
+
+      def build
+        validate!
+        @data
+      end
+
+      private
+
+      def validate!
+        # Проверка обязательных полей
+        raise ValidationError, "Weight is required" unless @data.dig(:parcel, :measures, :weight)
+        raise ValidationError, "Sender type is required" unless @data.dig(:sender, :type)
+        raise ValidationError, "Recipient type is required" unless @data.dig(:recipient, :type)
+
+        # Проверка логики
+        if @data.dig(:addons, :cash_on_delivery) && !@data.dig(:addons, :declared_value)
+          raise ValidationError, "Declared value is required when cash on delivery is set"
+        end
+
+        # Проверка международных отправлений
+        if @data.dig(:parcel, :arrival, :country) != "BY"
+          if @data[:cp72].nil? || @data[:cp72].empty?
+            raise ValidationError, "Customs declaration is required for international parcels"
+          end
+        end
+      end
+    end
+  end
+end 

data/lib/belpost/retry.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Belpost
+  class Retry
+    MAX_RETRIES = 3
+    INITIAL_DELAY = 1
+
+    def self.with_retry(max_retries: MAX_RETRIES, initial_delay: INITIAL_DELAY)
+      retries = 0
+      delay = initial_delay
+
+      begin
+        yield
+      rescue NetworkError, TimeoutError, ServerError => e
+        retries += 1
+        if retries <= max_retries
+          sleep(delay)
+          delay *= 2
+          retry
+        else
+          raise e
+        end
+      end
+    end
+  end
+end 

data/lib/belpost/validations/parcel_schema.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "dry/schema"
+
+module Belpost
+  # rubocop:disable Metrics/ModuleLength
+  module Validation
+    # Validation schema for parcel_data
+    # rubocop:disable Metrics/BlockLength
+    ParcelSchema = Dry::Schema.JSON do
+      required(:parcel).hash do
+        required(:type).filled(:string, included_in?: %w[package small_package small_valued_package ems])
+        required(:attachment_type).filled(:string, included_in?: %w[products documents])
+        required(:measures).hash do
+          required(:weight).filled(:integer, gt?: 0)
+          optional(:long).value(:integer, gt?: 0)
+          optional(:width).value(:integer, gt?: 0)
+          optional(:height).value(:integer, gt?: 0)
+        end
+        required(:departure).hash do
+          required(:country).filled(:string, eql?: "BY")
+          required(:place).filled(:string, included_in?: %w[post_office])
+          optional(:place_uuid).maybe(:string)
+        end
+        required(:arrival).hash do
+          required(:country).filled(:string)
+          required(:place).filled(:string, included_in?: %w[post_office])
+          optional(:place_uuid).maybe(:string)
+        end
+        optional(:s10code).maybe(:string)
+      end
+
+      optional(:addons).hash do
+        optional(:cash_on_delivery).maybe(:hash) do
+          required(:currency).filled(:string, eql?: "BYN")
+          required(:value).filled(:float, gt?: 0)
+        end
+        optional(:declared_value).maybe(:hash) do
+          required(:currency).filled(:string, eql?: "BYN")
+          required(:value).filled(:float, gt?: 0)
+        end
+        optional(:IOSS).maybe(:string)
+        optional(:registered_notification).maybe(:string)
+        optional(:simple_notification).maybe(:bool)
+        optional(:sms_notification).maybe(:bool)
+        optional(:email_notification).maybe(:bool)
+        optional(:priority_parcel).maybe(:bool)
+        optional(:attachment_inventory).maybe(:bool)
+        optional(:paid_shipping).maybe(:bool)
+        optional(:careful_fragile).maybe(:bool)
+        optional(:bulky).maybe(:bool)
+        optional(:ponderous).maybe(:bool)
+        optional(:payment_upon_receipt).maybe(:bool)
+        optional(:hand_over_personally).maybe(:bool)
+        optional(:return_of_documents).maybe(:bool)
+        optional(:open_upon_delivery).maybe(:bool)
+        optional(:delivery_to_work).maybe(:bool)
+        optional(:time_of_delivery).maybe(:hash) do
+          required(:type).filled(:string, included_in?: %w[level1 level2 level3 level4])
+          optional(:time_interval).hash do
+            required(:from).filled(:string)
+            required(:to).filled(:string)
+          end
+        end
+      end
+
+      required(:sender).hash do
+        required(:type).filled(:string, included_in?: %w[legal_person sole_proprietor])
+        required(:info).hash do
+          required(:organization_name).filled(:string)
+          optional(:taxpayer_number).maybe(:string)
+          optional(:bank).maybe(:string)
+          optional(:IBAN).maybe(:string)
+          optional(:BIC).maybe(:string)
+        end
+        required(:location).hash do
+          required(:code).filled(:string)
+          required(:region).filled(:string)
+          required(:district).filled(:string)
+          required(:locality).hash do
+            required(:type).filled(:string)
+            required(:name).filled(:string)
+          end
+          required(:road).hash do
+            required(:type).filled(:string)
+            required(:name).filled(:string)
+          end
+          required(:building).filled(:string)
+          optional(:housing).maybe(:string)
+          optional(:apartment).maybe(:string)
+        end
+        required(:email).filled(:string)
+        required(:phone).filled(:string)
+      end
+
+      required(:recipient).hash do
+        required(:type).filled(:string, included_in?: %w[natural_person legal_person sole_proprietor])
+        required(:info).hash do
+          optional(:organization_name).maybe(:string)
+          optional(:first_name).maybe(:string)
+          optional(:second_name).maybe(:string)
+          optional(:last_name).maybe(:string)
+        end
+        required(:location).hash do
+          optional(:code).maybe(:string)
+          optional(:region).maybe(:string)
+          optional(:district).maybe(:string)
+          optional(:locality).maybe(:hash) do
+            optional(:type).maybe(:string)
+            optional(:name).maybe(:string)
+          end
+          optional(:road).maybe(:hash) do
+            optional(:type).maybe(:string)
+            optional(:name).maybe(:string)
+          end
+          optional(:building).maybe(:string)
+          optional(:housing).maybe(:string)
+          optional(:apartment).maybe(:string)
+          optional(:address).maybe(:string)
+        end
+        optional(:email).maybe(:string)
+        required(:phone).filled(:string)
+      end
+
+      optional(:cp72).hash do
+        optional(:items).array(:hash) do
+          required(:name).filled(:string)
+          required(:local).filled(:string)
+          required(:unit).hash do
+            required(:local).filled(:string)
+            required(:en).filled(:string)
+          end
+          required(:count).filled(:integer, gt?: 0)
+          required(:weight).filled(:integer, gt?: 0)
+          required(:price).hash do
+            required(:currency).filled(:string)
+            required(:value).filled(:float, gt?: 0)
+          end
+          optional(:code).maybe(:string)
+          optional(:country).maybe(:string)
+        end
+        optional(:price).hash do
+          required(:currency).filled(:string)
+          required(:value).filled(:float, gt?: 0)
+        end
+        optional(:category).filled(:string, included_in?: %w[gift documents sample returned_goods merchandise other])
+        optional(:explanation).maybe(:string)
+        optional(:comments).maybe(:string)
+        optional(:invoice).maybe(:string)
+        optional(:licences).array(:string)
+        optional(:certificates).array(:string)
+      end
+    end
+    # rubocop:enable Metrics/BlockLength
+  end
+  # rubocop:enable Metrics/ModuleLength
+end

data/lib/belpost/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Belpost
+  VERSION = "0.1.0"
+end

data/lib/belpost.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "dotenv/load"
+
+require_relative "belpost/version"
+require_relative "belpost/configuration"
+require_relative "belpost/client"
+require_relative "belpost/errors"
+require_relative "belpost/retry"
+require_relative "belpost/models/parcel"
+require_relative "belpost/models/api_response"
+require_relative "belpost/models/customs_declaration"
+require_relative "belpost/models/parcel_builder"
+require_relative "belpost/validations/parcel_schema"
+
+# Module for working with Belpochta API.
+# Provides an interface for configuring and interacting with the API.
+module Belpost
+  class Error < StandardError; end
+
+  # Setting up the API configuration.
+  # @yieldparam config [Belpost::Configuration] configuration object.
+  def self.configure
+    yield configuration
+  end
+
+  # Returns the current configuration.
+  # @return [Belpost::Configuration]
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # Resets the configuration to default values.
+  def self.reset
+    @configuration = Configuration.new
+  end
+end