belpost 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c53d02403855e383fbb7d309ddeeeec66b2065303321cdde544d0e4fa6aba93e
+  data.tar.gz: aef5e4c2911ae80fca64dff3fb347cbf270ca66ea82da3905d3446a65efd543e
+SHA512:
+  metadata.gz: cfef1ca328d78d3ff55335a2271ba505e02ef2a95af81924a43acc736fc1a09828197a5075bc501d219ed60847dcf606eea082a68d7617769a5cbc6a94395ff4
+  data.tar.gz: ffe48fcfa53026d756eccc552db0cdac37c17aed4b14489852d51a51d2a6ae97e9f931bbd7babcd2842232003f807152c550e315f7c9bee34446955994cb05f4

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,13 @@
+AllCops:
+  TargetRubyVersion: 2.6
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/README.md

@@ -0,0 +1,334 @@
+# Belpost
+
+Клиент для работы с Belpochta API (Белпочта).
+
+## Установка
+
+Добавьте эту строку в Gemfile вашего приложения:
+
+```ruby
+gem 'belpost'
+```
+
+И выполните:
+
+```bash
+$ bundle install
+```
+
+Или установите самостоятельно:
+
+```bash
+$ gem install belpost
+```
+
+## Настройка
+
+Настройте клиент для работы с API Белпочты:
+
+```ruby
+require 'belpost'
+
+Belpost.configure do |config|
+  config.jwt_token = 'ваш_jwt_токен_от_Белпочты'
+  config.base_url = 'https://api.belpost.by'
+  config.timeout = 30 # Таймаут в секундах (по умолчанию 10)
+end
+```
+
+Вы также можете использовать переменные окружения:
+
+```
+BELPOST_JWT_TOKEN=ваш_jwt_токен_от_Белпочты
+BELPOST_BASE_URL=https://api.belpost.by
+BELPOST_TIMEOUT=30
+```
+
+## Использование
+
+### Создание посылки
+
+#### Базовый пример
+
+```ruby
+client = Belpost::Client.new
+
+parcel_data = {
+  parcel: {
+    type: "package",
+    attachment_type: "products",
+    measures: {
+      weight: 12
+    },
+    departure: {
+      country: "BY",
+      place: "post_office"
+    },
+    arrival: {
+      country: "BY",
+      place: "post_office"
+    }
+  },
+  addons: {
+    declared_value: {
+      currency: "BYN",
+      value: 100
+    },
+    cash_on_delivery: {
+      currency: "BYN",
+      value: 10
+    }
+  },
+  sender: {
+    type: "legal_person",
+    info: {
+      organization_name: "ООО \"Компания\"",
+      taxpayer_number: "123456789",
+      IBAN: "BY26BAPB30123418400100000000",
+      BIC: "BAPBBY2X",
+      bank: "ОАО 'БЕЛАГРОПРОМБАНК'"
+    },
+    location: {
+      code: "225212",
+      region: "Брестская",
+      district: "Березовский",
+      locality: {
+        type: "город",
+        name: "Береза"
+      },
+      road: {
+        type: "улица",
+        name: "Ленина"
+      },
+      building: "1",
+      housing: "",
+      apartment: ""
+    },
+    email: "test@example.com",
+    phone: "375291234567"
+  },
+  recipient: {
+    type: "natural_person",
+    info: {
+      first_name: "Иван",
+      second_name: "Иванович",
+      last_name: "Иванов"
+    },
+    location: {
+      code: "231365",
+      region: "Гродненская",
+      district: "Ивьевский",
+      locality: {
+        type: "деревня",
+        name: "Дуды"
+      },
+      road: {
+        type: "улица",
+        name: "Центральная"
+      },
+      building: "1",
+      housing: "",
+      apartment: ""
+    },
+    email: "",
+    phone: "375291234567"
+  }
+}
+
+response = client.create_parcel(parcel_data)
+puts "Трекинг код: #{response["data"]["parcel"]["s10code"]}"
+```
+
+#### Использование ParcelBuilder
+
+```ruby
+client = Belpost::Client.new
+
+# Создание внутренней посылки
+parcel_data = Belpost::Models::ParcelBuilder.new
+  .with_type("package")
+  .with_attachment_type("products")
+  .with_weight(1500) # вес в граммах
+  .with_dimensions(300, 200, 100) # длина, ширина, высота в мм
+  .to_country("BY")
+  .with_declared_value(100)
+  .with_cash_on_delivery(50)
+  .add_service(:simple_notification)
+  .add_service(:email_notification)
+  .from_legal_person("ООО \"Компания\"")
+  .with_sender_details(
+    taxpayer_number: "123456789",
+    bank: "ОАО 'БЕЛАГРОПРОМБАНК'",
+    iban: "BY26BAPB30123418400100000000",
+    bic: "BAPBBY2X"
+  )
+  .with_sender_location(
+    postal_code: "225212",
+    region: "Брестская",
+    district: "Березовский",
+    locality_type: "город",
+    locality_name: "Береза",
+    road_type: "улица",
+    road_name: "Ленина",
+    building: "1"
+  )
+  .with_sender_contact(
+    email: "test@example.com",
+    phone: "375291234567"
+  )
+  .to_natural_person(
+    first_name: "Иван",
+    last_name: "Иванов", 
+    second_name: "Иванович"
+  )
+  .with_recipient_location(
+    postal_code: "231365",
+    region: "Гродненская",
+    district: "Ивьевский",
+    locality_type: "деревня",
+    locality_name: "Дуды",
+    road_type: "улица",
+    road_name: "Центральная",
+    building: "1"
+  )
+  .with_recipient_contact(
+    phone: "375291234567"
+  )
+  .build
+
+response = client.create_parcel(parcel_data)
+puts "Трекинг код: #{response["data"]["parcel"]["s10code"]}"
+```
+
+#### Создание международной посылки с таможенной декларацией
+
+```ruby
+client = Belpost::Client.new
+
+# Создание таможенной декларации
+customs_declaration = Belpost::Models::CustomsDeclaration.new
+customs_declaration.set_category("gift")
+customs_declaration.set_price("USD", 50)
+customs_declaration.add_item(
+  {
+    name: "Книга",
+    local: "Книга",
+    unit: {
+      local: "ШТ",
+      en: "PCS"
+    },
+    count: 1,
+    weight: 500,
+    price: {
+      currency: "USD",
+      value: 50
+    },
+    country: "BY"
+  }
+)
+
+# Создание международной посылки
+parcel_data = Belpost::Models::ParcelBuilder.new
+  .with_type("package")
+  .with_attachment_type("products")
+  .with_weight(500)
+  .to_country("DE") # Германия
+  .with_declared_value(50, "USD")
+  .from_legal_person("ООО \"Компания\"")
+  .with_sender_location(
+    postal_code: "225212",
+    region: "Брестская",
+    district: "Березовский",
+    locality_type: "город",
+    locality_name: "Береза",
+    road_type: "улица",
+    road_name: "Ленина",
+    building: "1"
+  )
+  .with_sender_contact(
+    email: "test@example.com",
+    phone: "375291234567"
+  )
+  .to_natural_person(
+    first_name: "John",
+    last_name: "Doe"
+  )
+  .with_foreign_recipient_location(
+    postal_code: "10115",
+    locality: "Berlin",
+    address: "Unter den Linden 77"
+  )
+  .with_recipient_contact(
+    phone: "4901234567890"
+  )
+  .with_customs_declaration(customs_declaration)
+  .build
+
+response = client.create_parcel(parcel_data)
+puts "Трекинг код: #{response["data"]["parcel"]["s10code"]}"
+```
+
+### Получение списка доступных стран
+
+```ruby
+client = Belpost::Client.new
+countries = client.fetch_available_countries
+puts countries
+```
+
+### Получение данных для валидации почтового отправления
+
+```ruby
+client = Belpost::Client.new
+validation_data = client.validate_postal_delivery("BY")
+puts validation_data
+```
+
+### Получение кодов HS для таможенного декларирования
+
+```ruby
+client = Belpost::Client.new
+hs_codes = client.fetch_hs_codes
+puts hs_codes
+```
+
+## Обработка ошибок
+
+Клиент может выбрасывать следующие исключения:
+
+- `Belpost::ConfigurationError` - ошибка конфигурации
+- `Belpost::ValidationError` - ошибка валидации данных
+- `Belpost::ApiError` - базовая ошибка API
+- `Belpost::AuthenticationError` - ошибка аутентификации
+- `Belpost::InvalidRequestError` - ошибка запроса
+- `Belpost::RateLimitError` - превышен лимит запросов
+- `Belpost::ServerError` - ошибка сервера
+- `Belpost::NetworkError` - сетевая ошибка
+- `Belpost::TimeoutError` - таймаут запроса
+
+Пример обработки ошибок:
+
+```ruby
+begin
+  client = Belpost::Client.new
+  response = client.create_parcel(parcel_data)
+rescue Belpost::ValidationError => e
+  puts "Ошибка валидации: #{e.message}"
+rescue Belpost::AuthenticationError => e
+  puts "Ошибка аутентификации: #{e.message}"
+rescue Belpost::ApiError => e
+  puts "Ошибка API: #{e.message}"
+end
+```
+
+## Документация
+
+Полная документация по API Белпочты доступна в официальной документации.
+
+## Разработка
+
+После клонирования репозитория выполните `bin/setup` для установки зависимостей. Затем выполните `rake spec` для запуска тестов.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/belpost.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "lib/belpost/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "belpost"
+  spec.version = Belpost::VERSION
+  spec.authors = ["KuberLite"]
+  spec.email = ["kuberlite@gmail.com"]
+
+  spec.summary = "Belpost API wrapper"
+  spec.description = "Gem for working with the 'Belpost' delivery service via API"
+  spec.homepage = "https://github.com/KuberLite/belpost"
+  spec.required_ruby_version = ">= 2.6.0"
+  spec.license = "MIT"
+
+  spec.metadata = {
+    "bug_tracker_uri" => "https://github.com/KuberLite/belpost/issues",
+    "changelog_uri" => "https://github.com/KuberLite/belpost/releases",
+    "source_code_uri" => "https://github.com/belpost/evropochta",
+    "homepage_uri" => spec.homepage,
+    "rubygems_mfa_required" => "true"
+  }
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "dotenv"
+  spec.add_dependency "dry-validation", "~> 1.0"
+end

data/lib/belpost/api_service.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "logger"
+
+module Belpost
+  # Service class for handling HTTP requests to the BelPost API.
+  class ApiService
+    # Initializes a new instance of the ApiService.
+    #
+    # @param base_url [String] The base URL of the API.
+    # @param jwt_token [String] The JWT token for authentication.
+    # @param timeout [Integer] The request timeout in seconds (default: 10).
+    # @param logger [Logger] The logger for logging requests and responses.
+    def initialize(base_url:, jwt_token:, timeout: 10, logger: Logger.new($stdout))
+      @base_url = base_url
+      @jwt_token = jwt_token
+      @timeout = timeout
+      @logger = logger
+    end
+
+    # Performs a GET request to the specified path.
+    #
+    # @param path [String] The API endpoint path.
+    # @return [Models::ApiResponse] The parsed JSON response from the API.
+    def get(path)
+      Retry.with_retry do
+        uri = URI("#{@base_url}#{path}")
+        request = Net::HTTP::Get.new(uri)
+        add_headers(request)
+
+        log_request(request)
+        response = execute_request(uri, request)
+        log_response(response)
+
+        begin
+          Models::ApiResponse.new(
+            data: JSON.parse(response.body),
+            status_code: response.code.to_i,
+            headers: response.to_hash
+          )
+        rescue JSON::ParserError => e
+          raise ParseError, "Failed to parse JSON response: #{e.message}"
+        end
+      end
+    end
+
+    # Performs a POST request to the specified path with the given body.
+    #
+    # @param path [String] The API endpoint path.
+    # @param body [Hash] The request body as a hash.
+    # @return [Models::ApiResponse] The parsed JSON response from the API.
+    def post(path, body)
+      Retry.with_retry do
+        uri = URI("#{@base_url}#{path}")
+        request = Net::HTTP::Post.new(uri)
+        add_headers(request)
+        request.body = body.to_json
+
+        log_request(request)
+        response = execute_request(uri, request)
+        log_response(response)
+
+        begin
+          Models::ApiResponse.new(
+            data: JSON.parse(response.body),
+            status_code: response.code.to_i,
+            headers: response.to_hash
+          )
+        rescue JSON::ParserError => e
+          raise ParseError, "Failed to parse JSON response: #{e.message}"
+        end
+      end
+    end
+    
+    # Performs a PUT request to the specified path with the given body.
+    #
+    # @param path [String] The API endpoint path.
+    # @param body [Hash] The request body as a hash.
+    # @return [Models::ApiResponse] The parsed JSON response from the API.
+    def put(path, body)
+      Retry.with_retry do
+        uri = URI("#{@base_url}#{path}")
+        request = Net::HTTP::Put.new(uri)
+        add_headers(request)
+        request.body = body.to_json
+
+        log_request(request)
+        response = execute_request(uri, request)
+        log_response(response)
+
+        begin
+          Models::ApiResponse.new(
+            data: JSON.parse(response.body),
+            status_code: response.code.to_i,
+            headers: response.to_hash
+          )
+        rescue JSON::ParserError => e
+          raise ParseError, "Failed to parse JSON response: #{e.message}"
+        end
+      end
+    end
+    
+    # Performs a DELETE request to the specified path.
+    #
+    # @param path [String] The API endpoint path.
+    # @return [Models::ApiResponse] The parsed JSON response from the API.
+    def delete(path)
+      Retry.with_retry do
+        uri = URI("#{@base_url}#{path}")
+        request = Net::HTTP::Delete.new(uri)
+        add_headers(request)
+
+        log_request(request)
+        response = execute_request(uri, request)
+        log_response(response)
+
+        begin
+          Models::ApiResponse.new(
+            data: JSON.parse(response.body),
+            status_code: response.code.to_i,
+            headers: response.to_hash
+          )
+        rescue JSON::ParserError => e
+          raise ParseError, "Failed to parse JSON response: #{e.message}"
+        end
+      end
+    end
+
+    private
+
+    # Adds standard headers to the HTTP request.
+    #
+    # @param request [Net::HTTP::Request] The HTTP request object.
+    def add_headers(request)
+      request["Authorization"] = "Bearer #{@jwt_token}"
+      request["Accept"] = "application/json"
+      request["Content-Type"] = "application/json"
+    end
+
+    # Executes the HTTP request and processes the response.
+    #
+    # @param uri [URI] The URI of the request.
+    # @param request [Net::HTTP::Request] The HTTP request object.
+    # @return [Net::HTTP::Response] The HTTP response object.
+    # @raise [Belpost::ApiError] If the API returns an error response.
+    def execute_request(uri, request)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true if uri.scheme == "https"
+      http.read_timeout = @timeout
+
+      begin
+        response = http.request(request)
+        handle_response(response)
+      rescue Net::OpenTimeout, Net::ReadTimeout
+        raise RequestError, "Request timed out after #{@timeout} seconds"
+      rescue Net::HTTPError => e
+        case e.response.code
+        when "401", "403"
+          raise AuthenticationError.new(
+            "Authentication failed",
+            status_code: e.response.code.to_i,
+            response_body: e.response.body
+          )
+        when "429"
+          raise RateLimitError.new(
+            "Rate limit exceeded",
+            status_code: e.response.code.to_i,
+            response_body: e.response.body
+          )
+        when "400"
+          raise InvalidRequestError.new(
+            "Invalid request",
+            status_code: e.response.code.to_i,
+            response_body: e.response.body
+          )
+        else
+          raise ServerError.new(
+            "Server error",
+            status_code: e.response.code.to_i,
+            response_body: e.response.body
+          )
+        end
+      rescue StandardError => e
+        raise NetworkError, "Network error: #{e.message}"
+      end
+    end
+
+    def handle_response(response)
+      case response.code
+      when "200"
+        response
+      when "401", "403"
+        raise AuthenticationError.new(
+          "Authentication failed",
+          status_code: response.code.to_i,
+          response_body: response.body
+        )
+      when "429"
+        raise RateLimitError.new(
+          "Rate limit exceeded",
+          status_code: response.code.to_i,
+          response_body: response.body
+        )
+      when "400"
+        raise InvalidRequestError.new(
+          "Invalid request",
+          status_code: response.code.to_i,
+          response_body: response.body
+        )
+      else
+        raise ServerError.new(
+          "Server error",
+          status_code: response.code.to_i,
+          response_body: response.body
+        )
+      end
+    end
+
+    def log_request(request)
+      @logger.info("Making #{request.method} request to #{request.uri}")
+      @logger.debug("Request headers: #{request.to_hash}")
+      @logger.debug("Request body: #{request.body}") if request.body
+    end
+
+    def log_response(response)
+      @logger.info("Received response with status #{response.code}")
+      @logger.debug("Response headers: #{response.to_hash}")
+      @logger.debug("Response body: #{response.body}")
+    end
+  end
+end