cdek 0.3.9

data/app/controllers/cdek/widget_service_controller.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Cdek
+  # Прокси-эндпоинт для JS-виджета ПВЗ СДЭК (cdek-it/widget@3).
+  #
+  # Виджет ожидает servicePath, который умеет:
+  #   * GET  ?action=offices&<фильтры>     -> CDEK API /deliverypoints
+  #   * POST {"action":"calculate", ...}   -> CDEK API /calculator/tarifflist
+  #
+  # Это Ruby-аналог dist/service.php из репозитория cdek-it/widget,
+  # построенный поверх нашего тонкого клиента (он же берёт на себя OAuth2 и
+  # маппинг ошибок).
+  #
+  # Эндпоинт публичный read-only — не меняет состояние хост-приложения,
+  # авторизация выполняется на нашей стороне CDEK-токенами. CSRF полностью
+  # пропускаем (skip_forgery_protection) — виджет не знает о Rails-токенах,
+  # а raise/null_session засоряют логи строкой
+  # "Can't verify CSRF token authenticity" на каждый POST виджета.
+  #
+  # ВАЖНО: wrap_parameters принудительно отключён. По умолчанию Rails для
+  # JSON-запросов оборачивает body в ключ, совпадающий с именем контроллера
+  # (`widget_service`), и это удваивает все поля запроса. Удвоенные поля
+  # утекали в CDEK API как лишний ключ "widget_service" — CDEK его молча
+  # игнорировал (200 OK), но логи и сетевой трафик засорялись копией.
+  class WidgetServiceController < ::ActionController::Base
+    skip_forgery_protection
+    wrap_parameters false
+
+    # Имя ключа, под который Rails-обёртка кладёт дубликат параметров,
+    # если wrap_parameters всё же сработает (например, при переопределении
+    # на уровне ApplicationController наследниками). Удаляется на всякий
+    # случай вторым эшелоном защиты.
+    WRAPPER_KEY = "widget_service"
+    private_constant :WRAPPER_KEY
+
+    # Служебные ключи Rails-роутинга и виджета, которые не должны утечь
+    # в тело запроса к CDEK API.
+    EXCLUDED_PARAM_KEYS = %w[action controller format].freeze
+    private_constant :EXCLUDED_PARAM_KEYS
+
+    def call
+      cdek_action = cdek_request_action
+
+      case cdek_action
+      when "offices"
+        render json: Cdek.client.get("/deliverypoints", params: cdek_filtered_params)
+      when "calculate"
+        render json: Cdek.client.post("/calculator/tarifflist", body: cdek_filtered_params)
+      else
+        render json: { message: "Unknown action: #{cdek_action.inspect}" }, status: :bad_request
+      end
+    rescue Cdek::ConfigurationError => e
+      render json: { message: e.message }, status: :service_unavailable
+    rescue Cdek::ApiError => e
+      status = e.status.to_i.positive? ? e.status : 502
+      render json: { message: e.message, errors: e.errors, body: e.body }, status: status
+    rescue Cdek::Error => e
+      render json: { message: e.message }, status: :bad_gateway
+    end
+
+    private
+
+      # `action` виджет шлёт либо как query-параметр (GET), либо в JSON-теле (POST).
+      def cdek_request_action
+        request.query_parameters["action"].presence ||
+          request.request_parameters["action"].presence
+      end
+
+      # Все параметры запроса, кроме служебных Rails-роутинга и Rails-обёртки.
+      # Передаются в CDEK API как есть.
+      def cdek_filtered_params
+        request.query_parameters
+               .merge(request.request_parameters)
+               .except(*EXCLUDED_PARAM_KEYS, WRAPPER_KEY)
+               .to_h
+      end
+  end
+end

data/app/helpers/cdek/widget_helper.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Cdek
+  # Cdek::WidgetHelper — модуль, который Cdek::Engine автоматически подключает
+  # ко всем контроллерам хост-приложения. Делает доступным в любой view
+  # хелпер `cdek_widget_tag`, который рендерит блок-контейнер для JS-виджета
+  # ПВЗ СДЭК со всеми data-* атрибутами для Stimulus.
+  module WidgetHelper
+    # Рендерит блок-контейнер для JS-виджета. Виджет сам ставит карту,
+    # список ПВЗ и фильтры — нам нужно только дать ему div и Yandex-ключ.
+    #
+    # Параметры (все необязательные):
+    #   api_key:           ключ Yandex Maps JS API (по умолчанию — ENV["YANDEX_MAPS_API_KEY"])
+    #   default_city:      город «по умолчанию» (например, "Москва" или нечто из cookie)
+    #   sender_city:       город отправителя текстом (для тарифа в виджете, fallback)
+    #   sender_city_code:  CDEK-код города отправителя, число (предпочтительный
+    #                      способ — без него CDEK возвращает только дверь-* тарифы
+    #                      и виджет не может посчитать стоимость склад-склад,
+    #                      показывая "Выберите тариф").
+    #   goods:             массив хэшей габаритов и веса для расчёта тарифа.
+    #                      Каждый элемент: { width: Integer (см), height: Integer (см),
+    #                      length: Integer (см), weight: Integer (г) }. Гем не
+    #                      подставляет дефолтные габариты: хост-приложение должно
+    #                      собрать массив из реальных cart-items и передать сюда.
+    #   modal_id:          id модалки-обёртки — для авто-закрытия по выбору пункта
+    #   field_*:           DOM-id скрытых input'ов формы заказа, куда писать данные
+    #                      о выбранном пункте (по умолчанию совпадают с конвенциями,
+    #                      см. README)
+    #   label_selector:    CSS-селектор лейбла «Выбран пункт …» (по умолчанию
+    #                      `[data-cdek-widget-label]`)
+    #   address_selector:  CSS-селектор адреса выбранного пункта (по умолчанию
+    #                      `#order_cdek_point_address_view`)
+    #   height:            высота контейнера (по умолчанию `"600px"`).
+    def cdek_widget_tag(api_key: nil,
+                        default_city: "Москва",
+                        sender_city: "Москва",
+                        sender_city_code: nil,
+                        goods: nil,
+                        modal_id: nil,
+                        field_code:      "order_cdek_point_code",
+                        field_name:      "order_cdek_point_name",
+                        field_address:   "order_cdek_point_address",
+                        field_city_code: "order_cdek_city_code",
+                        label_selector:    "[data-cdek-widget-label]",
+                        address_selector:  "#order_cdek_point_address_view",
+                        height: "600px")
+      goods_payload = goods.is_a?(Array) ? goods : []
+
+      data = cdek_widget_data(
+        api_key:           api_key.presence || ENV["YANDEX_MAPS_API_KEY"].to_s,
+        default_city:      default_city,
+        sender_city:       sender_city,
+        sender_city_code:  sender_city_code.to_s,
+        goods_json:        JSON.generate(goods_payload),
+        service_path:      cdek_engine_widget_service_path,
+        script_url:        cdek_widget_asset_path,
+        modal_id:          modal_id.to_s,
+        field_code:        field_code,
+        field_name:        field_name,
+        field_address:     field_address,
+        field_city_code:   field_city_code,
+        label_selector:    label_selector,
+        address_selector:  address_selector
+      )
+
+      # Box-model + position:relative — обязательные условия для корректной
+      # отрисовки JS-виджета. Виджет внутри использует absolute-позиционирование
+      # для overlay'ев карты, тултипов и поповеров; без позиционированного
+      # предка они привязываются к ближайшему позиционированному элементу
+      # (часто — корню документа), что выкидывает их визуально за пределы
+      # виджета. Поэтому ставим эти стили inline у себя, чтобы хост-приложение
+      # ничего дополнительно не требовалось настраивать.
+      content_tag :div, class: "cdek-widget",
+                        data:  data,
+                        style: "display: block; position: relative; width: 100%; " \
+                               "height: #{height}; min-height: #{height};" do
+        safe_join [
+          content_tag(:div, "",
+                      class: "cdek-widget__root",
+                      data:  { cdek_widget_target: "root" },
+                      style: "position: relative; width: 100%; height: 100%;"),
+          content_tag(:div, "",
+                      class: "cdek-widget__error",
+                      data:  { cdek_widget_target: "error" },
+                      style: "display: none;")
+        ]
+      end
+    end
+
+    # Хэш data-* атрибутов для Stimulus-контроллера cdek-widget.
+    # Ключи в snake_case — Rails сам конвертит "_" в "-" в HTML.
+    def cdek_widget_data(api_key:, default_city:, sender_city:, sender_city_code:,
+                         goods_json:,
+                         service_path:, script_url:, modal_id:,
+                         field_code:, field_name:, field_address:, field_city_code:,
+                         label_selector:, address_selector:)
+      {
+        controller: "cdek-widget",
+        cdek_widget_service_path_value:      service_path,
+        cdek_widget_script_url_value:        script_url,
+        cdek_widget_api_key_value:           api_key,
+        cdek_widget_default_location_value:  default_city,
+        cdek_widget_sender_city_value:       sender_city,
+        cdek_widget_sender_city_code_value:  sender_city_code,
+        cdek_widget_goods_value:             goods_json,
+        cdek_widget_modal_id_value:          modal_id,
+        cdek_widget_field_code_value:        field_code,
+        cdek_widget_field_name_value:        field_name,
+        cdek_widget_field_address_value:     field_address,
+        cdek_widget_field_city_code_value:   field_city_code,
+        cdek_widget_label_selector_value:    label_selector,
+        cdek_widget_address_selector_value:  address_selector
+      }
+    end
+
+    # Путь до UMD-бандла виджета, вшитого в гем. Используется JS-контроллером
+    # для динамической загрузки скрипта по требованию.
+    def cdek_widget_asset_path
+      if respond_to?(:asset_path)
+        asset_path("cdek/widget.umd.js")
+      else
+        "/assets/cdek/widget.umd.js"
+      end
+    end
+
+    # Путь до прокси-эндпоинта из routes engine'а — корректно подхватит mount-точку.
+    def cdek_engine_widget_service_path
+      Cdek::Engine.routes.url_helpers.widget_service_path
+    end
+  end
+end

data/cdek.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "lib/cdek/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "cdek"
+  spec.version     = Cdek::VERSION
+  spec.authors     = ["Your Name"]
+  spec.email       = ["you@example.com"]
+
+  spec.summary     = "Ruby/Rails клиент и Engine для CDEK API v2 с виджетом ПВЗ"
+  spec.description = "Тонкий клиент для CDEK API v2 без внешних рантайм-зависимостей: " \
+                     "конфигурация, иерархия ошибок, автоматическое управление OAuth2-токеном. " \
+                     "Поверх клиента — монтируемый Rails Engine с прокси-эндпоинтом, " \
+                     "вендорным JS-виджетом ПВЗ и Stimulus-контроллером."
+  spec.license     = "MIT"
+
+  spec.required_ruby_version = ">= 3.0"
+
+  # Включаем всё содержимое app/, config/ и lib/ (включая шаблоны генератора
+  # с расширениями .rb и .js, и вендорный UMD-бандл виджета).
+  spec.files = Dir[
+    "lib/**/*",
+    "app/**/*",
+    "config/**/*",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "cdek.gemspec"
+  ]
+  spec.require_paths = ["lib"]
+
+  spec.metadata = {
+    "rubygems_mfa_required" => "true"
+  }
+
+  spec.add_development_dependency "rake", "~> 13.0"
+end

data/config/routes.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+Cdek::Engine.routes.draw do
+  # Прокси для JS-виджета ПВЗ — единственный публичный маршрут гема.
+  # Виджет шлёт GET (action=offices) и POST (action=calculate) на один URL,
+  # поэтому match по обоим методам.
+  match "/widget_service",
+        to:   "widget_service#call",
+        via:  %i[get post],
+        as:   :widget_service
+end

data/lib/cdek/client.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Cdek
+  # Тонкий клиент-фасад над Cdek::Connection.
+  #
+  # Реализует «сырые» вызовы CDEK API v2 без дополнительной семантики.
+  # Высокоуровневые ресурсы (Calculator, Orders, Locations, Offices, Webhooks)
+  # будут добавлены в следующей итерации.
+  class Client
+    attr_reader :configuration, :connection
+
+    def initialize(configuration = Cdek.configuration)
+      @configuration = configuration
+      @connection    = Connection.new(configuration)
+    end
+
+    def get(path, params: nil, headers: {})
+      connection.authenticated_request(:get, path, params: params, headers: headers)
+    end
+
+    def post(path, body: nil, headers: {})
+      connection.authenticated_request(:post, path, body: body, headers: headers)
+    end
+
+    def patch(path, body: nil, headers: {})
+      connection.authenticated_request(:patch, path, body: body, headers: headers)
+    end
+
+    def put(path, body: nil, headers: {})
+      connection.authenticated_request(:put, path, body: body, headers: headers)
+    end
+
+    def delete(path, params: nil, headers: {})
+      connection.authenticated_request(:delete, path, params: params, headers: headers)
+    end
+
+    def reset_token!
+      connection.reset_token!
+    end
+  end
+end

data/lib/cdek/configuration.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Cdek
+  # Конфигурация гема.
+  #
+  # Cdek.configure do |config|
+  #   config.account         = ENV["CDEK_ACCOUNT"]
+  #   config.secure_password = ENV["CDEK_SECURE_PASSWORD"]
+  #   config.production_mode!
+  # end
+  class Configuration
+    PRODUCTION_URL = "https://api.cdek.ru/v2"
+    TEST_URL       = "https://api.edu.cdek.ru/v2"
+
+    # Тестовые учётные данные CDEK для песочницы публикуются в их документации.
+    # Указываются здесь только как ссылка для удобства, ничего не предзаполняется.
+    SANDBOX_ACCOUNT          = "EMscd6r9JnFiQ3bLoyjJY6eM78JrJceI"
+    SANDBOX_SECURE_PASSWORD  = "PjLZkKBHEiLK3YsHzqYDqQYj1pSwOaNB"
+
+    attr_accessor :account,
+                  :secure_password,
+                  :base_url,
+                  :timeout,
+                  :open_timeout,
+                  :logger,
+                  :user_agent
+
+    def initialize
+      @account         = nil
+      @secure_password = nil
+      @base_url        = TEST_URL
+      @timeout         = 15
+      @open_timeout    = 5
+      @logger          = nil
+      @user_agent      = "cdek-ruby/#{Cdek::VERSION}"
+    end
+
+    def test_mode!
+      @base_url = TEST_URL
+    end
+
+    def production_mode!
+      @base_url = PRODUCTION_URL
+    end
+
+    def use_sandbox_credentials!
+      @account         = SANDBOX_ACCOUNT
+      @secure_password = SANDBOX_SECURE_PASSWORD
+      test_mode!
+    end
+
+    def credentials_present?
+      account.to_s.strip.length.positive? && secure_password.to_s.strip.length.positive?
+    end
+  end
+end

data/lib/cdek/connection.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Cdek
+  # Низкоуровневый HTTP-коннект к CDEK API.
+  #
+  # Отвечает за:
+  # * получение и кэширование OAuth2 access_token (grant_type=client_credentials);
+  # * прозрачный ретрай запроса при 401 (один раз, со сбросом токена);
+  # * сериализацию JSON-тел и маппинг HTTP-статусов в иерархию Cdek::ApiError.
+  class Connection
+    JSON_CONTENT_TYPE     = "application/json"
+    FORM_CONTENT_TYPE     = "application/x-www-form-urlencoded"
+    TOKEN_PATH            = "/oauth/token"
+    TOKEN_REFRESH_LEEWAY  = 30 # секунд до истечения, после которых обновляем заранее
+
+    HTTP_METHOD_CLASSES = {
+      get:    Net::HTTP::Get,
+      post:   Net::HTTP::Post,
+      patch:  Net::HTTP::Patch,
+      put:    Net::HTTP::Put,
+      delete: Net::HTTP::Delete
+    }.freeze
+
+    attr_reader :configuration
+
+    def initialize(configuration)
+      @configuration     = configuration
+      @token_mutex       = Mutex.new
+      @access_token      = nil
+      @token_expires_at  = nil
+    end
+
+    # Выполняет авторизованный запрос. Любой ответ 2xx — возвращает распарсенное тело.
+    # Любая ошибка — поднимается как Cdek::ApiError или его наследник.
+    def authenticated_request(method, path, params: nil, body: nil, headers: {})
+      execute_authenticated(method, path, params, body, headers, retried: false)
+    end
+
+    # Сбрасывает кэшированный токен — следующая операция получит новый.
+    def reset_token!
+      @token_mutex.synchronize do
+        @access_token     = nil
+        @token_expires_at = nil
+      end
+    end
+
+    private
+
+    def execute_authenticated(method, path, params, body, headers, retried:)
+      auth_headers = headers.merge("Authorization" => "Bearer #{access_token}")
+      raw          = perform(method, path, params: params, body: body, headers: auth_headers)
+      outcome      = handle_response(raw)
+
+      if outcome == :reauth
+        raise AuthenticationError.new("CDEK: повторный 401 после обновления токена") if retried
+
+        reset_token!
+        execute_authenticated(method, path, params, body, headers, retried: true)
+      else
+        outcome
+      end
+    end
+
+    def access_token
+      @token_mutex.synchronize do
+        fetch_token! if token_invalid?
+        @access_token
+      end
+    end
+
+    def token_invalid?
+      @access_token.nil? ||
+        @token_expires_at.nil? ||
+        Time.now >= (@token_expires_at - TOKEN_REFRESH_LEEWAY)
+    end
+
+    def fetch_token!
+      unless configuration.credentials_present?
+        raise ConfigurationError,
+              "CDEK: не заданы учётные данные. Установите account и secure_password через Cdek.configure"
+      end
+
+      form = URI.encode_www_form(
+        grant_type:    "client_credentials",
+        client_id:     configuration.account,
+        client_secret: configuration.secure_password
+      )
+
+      raw    = perform_raw(:post, TOKEN_PATH,
+                           body: form,
+                           headers: { "Content-Type" => FORM_CONTENT_TYPE, "Accept" => JSON_CONTENT_TYPE })
+      parsed = parse_body(raw.body)
+
+      unless raw.is_a?(Net::HTTPSuccess)
+        raise AuthenticationError.new(
+          "CDEK: не удалось получить access_token",
+          status: raw.code.to_i,
+          body:   parsed,
+          errors: extract_errors(parsed)
+        )
+      end
+
+      @access_token     = parsed["access_token"]
+      @token_expires_at = Time.now + parsed["expires_in"].to_i
+    end
+
+    def perform(method, path, params: nil, body: nil, headers: {})
+      json_body         = body.nil? ? nil : JSON.generate(body)
+      effective_headers = headers.merge(
+        "Content-Type" => JSON_CONTENT_TYPE,
+        "Accept"       => JSON_CONTENT_TYPE
+      )
+      perform_raw(method, path, params: params, body: json_body, headers: effective_headers)
+    end
+
+    def perform_raw(method, path, params: nil, body: nil, headers: {})
+      uri     = build_uri(path, params)
+      request = build_request(method, uri, body, headers)
+      log_request(method, uri, body)
+      execute_http(uri, request).tap { |response| log_response(response) }
+    end
+
+    def build_uri(path, params)
+      base            = configuration.base_url.to_s.sub(%r{/+\z}, "")
+      normalized_path = path.start_with?("/") ? path : "/#{path}"
+      URI.parse("#{base}#{normalized_path}").tap do |uri|
+        uri.query = URI.encode_www_form(params) if params.is_a?(Hash) && params.any?
+      end
+    end
+
+    def build_request(method, uri, body, headers)
+      klass = HTTP_METHOD_CLASSES.fetch(method) do
+        raise ArgumentError, "Неподдерживаемый HTTP-метод: #{method.inspect}"
+      end
+
+      klass.new(uri.request_uri).tap do |req|
+        headers.each { |key, value| req[key] = value }
+        req["User-Agent"] = configuration.user_agent if configuration.user_agent
+        req.body = body if body
+      end
+    end
+
+    def execute_http(uri, request)
+      http             = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl     = (uri.scheme == "https")
+      http.read_timeout = configuration.timeout
+      http.open_timeout = configuration.open_timeout
+      http.request(request)
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise TimeoutError, "CDEK: таймаут запроса (#{e.message})"
+    rescue SocketError, Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, IOError => e
+      raise ConnectionError, "CDEK: ошибка соединения (#{e.message})"
+    end
+
+    def handle_response(response)
+      status = response.code.to_i
+      parsed = parse_body(response.body)
+
+      case response
+      when Net::HTTPSuccess
+        parsed
+      when Net::HTTPUnauthorized
+        :reauth
+      when Net::HTTPBadRequest
+        raise BadRequestError.new("CDEK: 400 Bad Request",
+                                  status: status, body: parsed, errors: extract_errors(parsed))
+      when Net::HTTPNotFound
+        raise NotFoundError.new("CDEK: 404 Not Found",
+                                status: status, body: parsed, errors: extract_errors(parsed))
+      when Net::HTTPTooManyRequests
+        raise RateLimitError.new("CDEK: 429 Too Many Requests",
+                                 status: status, body: parsed, errors: extract_errors(parsed))
+      when Net::HTTPServerError
+        raise ServerError.new("CDEK: серверная ошибка #{status}",
+                              status: status, body: parsed, errors: extract_errors(parsed))
+      else
+        raise ApiError.new("CDEK: неожиданный статус #{status}",
+                           status: status, body: parsed, errors: extract_errors(parsed))
+      end
+    end
+
+    def parse_body(body)
+      body.nil? || body.to_s.empty? ? {} : JSON.parse(body)
+    rescue JSON::ParserError
+      { "raw" => body.to_s }
+    end
+
+    def extract_errors(parsed)
+      parsed.is_a?(Hash) ? parsed["errors"] || parsed["requests"] : nil
+    end
+
+    def log_request(method, uri, body)
+      configuration.logger&.debug do
+        "[CDEK] #{method.to_s.upcase} #{uri} body=#{loggable_request_body(uri, body)}"
+      end
+    end
+
+    def log_response(response)
+      configuration.logger&.debug { "[CDEK] <- #{response.code} #{loggable_response_body(response)}" }
+    end
+
+    def loggable_request_body(uri, body)
+      if uri.path.end_with?(TOKEN_PATH)
+        "[FILTERED]"
+      else
+        body && truncate(body)
+      end
+    end
+
+    def loggable_response_body(response)
+      parsed = parse_body(response.body)
+
+      if parsed.is_a?(Hash) && parsed.key?("access_token")
+        truncate(JSON.generate(parsed.merge("access_token" => "[FILTERED]")))
+      else
+        truncate(response.body)
+      end
+    end
+
+    def truncate(text)
+      text.to_s[0, 500]
+    end
+  end
+end

data/lib/cdek/engine.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Cdek
+  # Cdek::Engine — монтируемый Rails Engine, который шипит весь стек интеграции
+  # с виджетом ПВЗ СДЭК «в коробке»:
+  #
+  #   * прокси-эндпоинт   /widget_service  (Cdek::WidgetServiceController)
+  #   * вендорный JS      /assets/cdek/widget.umd.js  (через asset pipeline)
+  #   * helper для view   cdek_widget_tag (Cdek::WidgetHelper)
+  #   * Stimulus-контроллер cdek_widget_controller.js (через генератор cdek:install)
+  #
+  # Подключение в хост-приложении:
+  #
+  #   # config/routes.rb
+  #   mount Cdek::Engine, at: "/cdek"
+  #
+  #   # любая view
+  #   = cdek_widget_tag api_key: ENV["YANDEX_MAPS_API_KEY"]
+  class Engine < ::Rails::Engine
+    isolate_namespace Cdek
+
+    # Перенесено из старого Cdek::Railtie — гарантируем, что у конфигурации
+    # есть логгер сразу после загрузки приложения.
+    initializer "cdek.set_default_logger" do
+      Cdek.configuration.logger ||= Rails.logger
+    end
+
+    # Asset pipeline (Sprockets / Propshaft) — точечно прекомпилируем UMD-бандл
+    # виджета, чтобы он попадал в production-сборку.
+    initializer "cdek.assets.precompile" do |app|
+      if app.config.respond_to?(:assets) && app.config.assets
+        app.config.assets.precompile += %w[cdek/widget.umd.js]
+      end
+    end
+
+    # Подключаем хелперы гема ко всем контроллерам хост-приложения,
+    # чтобы `cdek_widget_tag` был доступен в любой view без явных include.
+    initializer "cdek.include_helpers" do
+      ActiveSupport.on_load(:action_controller_base) do
+        helper Cdek::WidgetHelper
+      end
+    end
+  end
+end

data/lib/cdek/error.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Cdek
+  # Базовый класс для всех ошибок гема.
+  class Error < StandardError; end
+
+  # Ошибка конфигурации (например, отсутствуют креды).
+  class ConfigurationError < Error; end
+
+  # Ошибка ответа API. Доступны статус, тело и массив ошибок CDEK.
+  class ApiError < Error
+    attr_reader :status, :body, :errors
+
+    def initialize(message, status: nil, body: nil, errors: nil)
+      super(message)
+      @status = status
+      @body = body
+      @errors = errors
+    end
+  end
+
+  class AuthenticationError < ApiError; end
+  class BadRequestError    < ApiError; end
+  class NotFoundError      < ApiError; end
+  class RateLimitError     < ApiError; end
+  class ServerError        < ApiError; end
+
+  # Ошибки сетевого уровня.
+  class ConnectionError < Error; end
+  class TimeoutError    < ConnectionError; end
+end

data/lib/cdek/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Cdek
+  class Railtie < Rails::Railtie
+    initializer "cdek.set_default_logger" do
+      Cdek.configuration.logger ||= Rails.logger
+    end
+  end
+end