cdek 0.3.9

data/lib/cdek/resources/base.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Cdek
+  module Resources
+    # Базовый класс для high-level ресурсов CDEK API.
+    #
+    # Хранит ссылку на клиент. Конкретные ресурсы (Locations, Deliverypoints
+    # и т.п.) наследуются и проксируют вызовы в client.get/post/...
+    class Base
+      attr_reader :client
+
+      def initialize(client = Cdek.client)
+        @client = client
+      end
+    end
+  end
+end

data/lib/cdek/resources/deliverypoints.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Cdek
+  module Resources
+    # Список пунктов выдачи заказов (ПВЗ/Постамат) CDEK API v2.
+    # Эндпоинт: GET /deliverypoints
+    #
+    # Параметры (наиболее часто используемые):
+    # * city_code     — код города CDEK (получается через Locations#cities)
+    # * postal_code   — почтовый индекс
+    # * type          — "PVZ" | "POSTAMAT" | "ALL"
+    # * country_code  — двухбуквенный код страны (RU и т.п.)
+    # * region_code   — код региона
+    # * code          — код конкретного пункта (например MSK2181)
+    # * have_cashless / have_cash / allowed_cod / is_dressing_room —
+    #                   булевы фильтры
+    # * weight_min / weight_max — допустимый вес посылки
+    # * is_handout    — выдаёт ли посылки
+    # * is_reception  — принимает ли посылки
+    # * size / page   — пагинация
+    #
+    # Возвращает массив пунктов в формате CDEK API (массив Hash).
+    #
+    # Примеры:
+    #   Cdek.deliverypoints.list(city_code: 44, type: "PVZ", size: 100)
+    #   Cdek.deliverypoints.pvz_for_city(44)
+    #   Cdek.deliverypoints.find("MSK2181")
+    class Deliverypoints < Base
+      LIST_PATH    = "/deliverypoints"
+      DEFAULT_TYPE = "PVZ"
+
+      def list(params = {})
+        client.get(LIST_PATH, params: params.compact)
+      end
+
+      # Шорткат: ПВЗ по коду города. extra — дополнительные фильтры (например,
+      # have_cashless: true), которые мерджатся к city_code и type.
+      def pvz_for_city(city_code, extra = {})
+        list({ city_code: city_code, type: DEFAULT_TYPE }.merge(extra))
+      end
+
+      # Найти конкретный пункт по его коду (CDEK ID, например MSK2181).
+      # Возвращает Hash пункта или nil.
+      def find(code)
+        result = list(code: code, size: 1)
+        result.is_a?(Array) ? result.first : nil
+      end
+    end
+  end
+end

data/lib/cdek/resources/locations.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Cdek
+  module Resources
+    # Справочники локаций CDEK API v2.
+    #
+    # Тонкая обёртка над эндпоинтами:
+    # * GET /location/cities          — список городов
+    # * GET /location/regions         — список регионов
+    # * GET /location/suggest/cities  — подсказка городов по подстроке
+    #
+    # Параметры передаются как есть в query-string; обязательной нормализации
+    # или валидации не делаем — структура и набор параметров полностью
+    # соответствуют официальной документации CDEK. Значения nil автоматически
+    # отбрасываются, чтобы не попадать в URL пустыми ключами.
+    #
+    # Примеры:
+    #   Cdek.locations.cities(country_codes: "RU", city: "Москва", size: 5)
+    #   Cdek.locations.regions(country_codes: "RU", size: 10)
+    #   Cdek.locations.suggest_cities(name: "Моск", country_code: "RU")
+    #   Cdek.locations.find_city("Москва")
+    class Locations < Base
+      CITIES_PATH         = "/location/cities"
+      REGIONS_PATH        = "/location/regions"
+      SUGGEST_CITIES_PATH = "/location/suggest/cities"
+
+      def cities(params = {})
+        client.get(CITIES_PATH, params: params.compact)
+      end
+
+      def regions(params = {})
+        client.get(REGIONS_PATH, params: params.compact)
+      end
+
+      def suggest_cities(params = {})
+        client.get(SUGGEST_CITIES_PATH, params: params.compact)
+      end
+
+      # Удобный шорткат: найти первый город по точному названию (и стране).
+      # Возвращает Hash города или nil, если ничего не нашлось.
+      def find_city(name, country_codes: "RU", **extra)
+        list = cities({ city: name, country_codes: country_codes, size: 1 }.merge(extra))
+        list.is_a?(Array) ? list.first : nil
+      end
+    end
+  end
+end

data/lib/cdek/version.rb

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

data/lib/cdek.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "cdek/version"
+require "cdek/error"
+require "cdek/configuration"
+require "cdek/connection"
+require "cdek/client"
+require "cdek/resources/base"
+require "cdek/resources/locations"
+require "cdek/resources/deliverypoints"
+
+module Cdek
+  CLIENT_MUTEX = Mutex.new
+  private_constant :CLIENT_MUTEX
+
+  class << self
+    # Возвращает текущий объект конфигурации (создавая его при первом обращении).
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Блочный синтаксис настройки.
+    #
+    #   Cdek.configure do |config|
+    #     config.account         = ENV["CDEK_ACCOUNT"]
+    #     config.secure_password = ENV["CDEK_SECURE_PASSWORD"]
+    #     config.production_mode!
+    #   end
+    def configure
+      yield configuration
+    end
+
+    # Шареный клиент. Потокобезопасная мемоизация.
+    def client
+      CLIENT_MUTEX.synchronize { @client ||= Client.new(configuration) }
+    end
+
+    # Сбрасывает мемоизированный клиент (полезно после изменения конфигурации
+    # или в тестах).
+    def reset_client!
+      CLIENT_MUTEX.synchronize { @client = nil }
+    end
+
+    # Полный сброс — и конфигурации, и клиента.
+    def reset!
+      CLIENT_MUTEX.synchronize do
+        @configuration = nil
+        @client        = nil
+      end
+    end
+
+    # High-level ресурс «Локации» — справочники городов/регионов и suggest.
+    # По умолчанию использует шареный Cdek.client; можно передать кастомный
+    # клиент (например, в тестах с подменённым transport).
+    def locations(custom_client = client)
+      Resources::Locations.new(custom_client)
+    end
+
+    # High-level ресурс «Пункты выдачи» — список ПВЗ/постаматов по фильтрам.
+    def deliverypoints(custom_client = client)
+      Resources::Deliverypoints.new(custom_client)
+    end
+  end
+end
+
+# Rails Engine — подключает прокси-эндпоинт, виджет, helper. Подгружаем только
+# если хост — Rails-приложение. Версия гема без Rails (standalone скрипты,
+# CLI-утилиты) продолжит работать как тонкий клиент API.
+require "cdek/engine" if defined?(::Rails::Engine)

data/lib/generators/cdek/install/install_generator.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Cdek
+  module Generators
+    # bin/rails generate cdek:install
+    #
+    # Кладёт в хост-приложение:
+    #   * config/initializers/cdek.rb                              — настройка гема
+    #   * app/javascript/controllers/cdek_widget_controller.js     — Stimulus-контроллер виджета ПВЗ
+    #
+    # Сам Engine монтируется отдельной строкой в config/routes.rb пользователя:
+    #   mount Cdek::Engine, at: "/cdek"
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Создаёт config/initializers/cdek.rb и Stimulus-контроллер виджета ПВЗ."
+
+      def copy_initializer
+        template "cdek.rb", "config/initializers/cdek.rb"
+      end
+
+      def copy_stimulus_controller
+        copy_file "cdek_widget_controller.js",
+                  "app/javascript/controllers/cdek_widget_controller.js"
+      end
+
+      def print_post_install
+        say "\n========================================================================", :green
+        say "  Гем Cdek установлен.", :green
+        say "========================================================================", :green
+        say "  1) Добавьте маршрут в config/routes.rb:"
+        say "       mount Cdek::Engine, at: \"/cdek\""
+        say ""
+        say "  2) Заполните .env (или ENV) переменными:"
+        say "       CDEK_ACCOUNT=..."
+        say "       CDEK_SECURE_PASSWORD=..."
+        say "       YANDEX_MAPS_API_KEY=...   # ключ Yandex Maps JS API для карты виджета"
+        say ""
+        say "  3) Вставьте виджет в любую view, например в модалку оформления заказа:"
+        say "       = cdek_widget_tag api_key: ENV[\"YANDEX_MAPS_API_KEY\"],"
+        say "                         default_city: \"Москва\","
+        say "                         modal_id: \"cdek-points-modal\""
+        say ""
+        say "  4) Скрытые поля для приёма выбранного пункта (внутри order_form):"
+        say "       order_cdek_point_code"
+        say "       order_cdek_point_name"
+        say "       order_cdek_point_address"
+        say "       order_cdek_city_code"
+        say "     (DOM-id можно переопределить аргументами field_* у cdek_widget_tag.)"
+        say "========================================================================", :green
+      end
+    end
+  end
+end

data/lib/generators/cdek/install/templates/cdek.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Настройка гема Cdek.
+#
+# Учётные данные удобно хранить в Rails encrypted credentials или ENV.
+# В примере ниже используются ENV-переменные.
+Cdek.configure do |config|
+  config.account         = ENV["CDEK_ACCOUNT"]
+  config.secure_password = ENV["CDEK_SECURE_PASSWORD"]
+
+  # Контур CDEK API. По умолчанию — боевой (api.cdek.ru/v2). С боевыми
+  # учётными данными это правильный выбор и в development. Чтобы временно
+  # переключиться на песочницу (api.edu.cdek.ru/v2) — добавь в .env:
+  #
+  #   CDEK_SANDBOX=1
+  #
+  # либо явно поменяй вызов на config.test_mode!.
+  if ENV["CDEK_SANDBOX"].to_s.match?(/\A(1|true|yes|on)\z/i)
+    config.test_mode!
+  else
+    config.production_mode!
+  end
+
+  # Опциональная тонкая настройка:
+  # config.timeout      = 15
+  # config.open_timeout = 5
+  # config.user_agent   = "MyApp/1.0 (+https://example.com)"
+  config.logger = Rails.logger
+
+  # Быстрый старт с публичными тестовыми кредами CDEK (только для песочницы):
+  # config.use_sandbox_credentials!
+end

data/lib/generators/cdek/install/templates/cdek_widget_controller.js

@@ -0,0 +1,184 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Stimulus-контроллер виджета ПВЗ СДЭК.
+//
+// КРИТИЧНО: @cdek-it/widget@3 (UMD) ожидает параметр `root` как СТРОКОВЫЙ
+// ID DOM-элемента, не как сам DOM-объект. Внутри виджет вызывает
+// `document.getElementById(params.root)`. Если передать туда HTMLElement —
+// getElementById вернёт null, и виджет создаст «висячий» div в памяти,
+// продолжит делать запросы офисов (мы это видим в server-логах), но в
+// видимом DOM нашего root-таргета ничего не отрисует. Поэтому здесь мы
+// гарантируем, что у root-элемента есть уникальный id, и передаём
+// виджету именно строку.
+//
+// Про from / sender_city_code:
+// Если в `from` передавать только { address: "Москва" }, CDEK API не
+// возвращает склад-склад тарифы (только дверь-*), и виджет показывает
+// «Выберите тариф». Чтобы получить полный набор тарифов, нужно передать
+// CDEK-код города отправителя (см. справочник /location/cities). Если код
+// задан через data-cdek-widget-sender-city-code-value — используем его,
+// иначе fallback на address.
+//
+// Про goods:
+// CDEK считает тарифы по габаритам и весу отправления. Значение `goods`
+// должно приходить от хост-приложения через data-cdek-widget-goods-value.
+// Если массив не передан или невалиден, не подставляем статичные габариты:
+// виджет будет открыт без расчётных packages, чтобы не считать доставку
+// по выдуманным размерам.
+
+let _scriptPromise = null
+
+function ensureWidgetScript(url) {
+    if (typeof window.CDEKWidget !== "undefined") {
+        return Promise.resolve()
+    }
+    if (_scriptPromise) return _scriptPromise
+    _scriptPromise = new Promise((resolve, reject) => {
+        const s = document.createElement("script")
+        s.src = url
+        s.async = true
+        s.onload = () => resolve()
+        s.onerror = () => { _scriptPromise = null; reject(new Error("Не удалось загрузить скрипт виджета СДЭК")) }
+        document.head.appendChild(s)
+    })
+    return _scriptPromise
+}
+
+function setFieldValue(id, value) {
+    if (!id) return
+    const el = document.getElementById(id)
+    if (el) {
+        el.value = value == null ? "" : String(value)
+        el.dispatchEvent(new Event("change", { bubbles: true }))
+    }
+}
+
+function setText(selector, value) {
+    if (!selector) return
+    document.querySelectorAll(selector).forEach((el) => { el.textContent = value })
+}
+
+function parseGoods(rawJson) {
+    const trimmed = (rawJson || "").trim()
+    if (trimmed === "") return []
+    try {
+        const parsed = JSON.parse(trimmed)
+        if (Array.isArray(parsed)) return parsed
+        return []
+    } catch (_) {
+        return []
+    }
+}
+
+export default class extends Controller {
+    static targets = ["root", "error"]
+    static values = {
+        servicePath:     String,
+        scriptUrl:       String,
+        apiKey:          String,
+        defaultLocation: { type: String, default: "Москва" },
+        senderCity:      { type: String, default: "Москва" },
+        senderCityCode:  { type: String, default: "" },
+        goods:           { type: String, default: "" },
+        modalId:         { type: String, default: "" },
+        fieldCode:       { type: String, default: "order_cdek_point_code" },
+        fieldName:       { type: String, default: "order_cdek_point_name" },
+        fieldAddress:    { type: String, default: "order_cdek_point_address" },
+        fieldCityCode:   { type: String, default: "order_cdek_city_code" },
+        labelSelector:   { type: String, default: "[data-cdek-widget-label]" },
+        addressSelector: { type: String, default: "#order_cdek_point_address_view" }
+    }
+
+    connect() {
+        ensureWidgetScript(this.scriptUrlValue)
+            .then(() => this._mountWidget())
+            .catch((err) => this._showError(err && err.message ? err.message : "ошибка"))
+    }
+
+    disconnect() {
+        if (this._widget) {
+            try {
+                if (typeof this._widget.destroy === "function") this._widget.destroy()
+                else if (typeof this._widget.close === "function") this._widget.close()
+            } catch (_) { /* no-op */ }
+            this._widget = null
+        }
+    }
+
+    _mountWidget() {
+        if (!this.hasRootTarget) return
+        if (typeof window.CDEKWidget !== "function") {
+            this._showError("CDEKWidget недоступен после загрузки скрипта")
+            return
+        }
+
+        // Гарантируем уникальный DOM-id у root'а и передаём его виджету строкой.
+        if (!this.rootTarget.id) {
+            this.rootTarget.id = "cdek-widget-root-" + Math.random().toString(36).slice(2, 10)
+        }
+
+        // Если задан CDEK-код города отправителя — передаём его, иначе fallback
+        // на address. С code CDEK вернёт склад-склад тарифы; с одним address —
+        // только дверь-* (тогда виджет покажет "Выберите тариф" для офиса).
+        const senderCodeRaw = this.senderCityCodeValue.trim()
+        const senderCodeNum = senderCodeRaw === "" ? null : Number(senderCodeRaw)
+        const from = (senderCodeNum !== null && Number.isFinite(senderCodeNum))
+            ? { code: senderCodeNum }
+            : { address: this.senderCityValue }
+
+        const goods = parseGoods(this.goodsValue)
+        const widgetOptions = {
+            root:                this.rootTarget.id,
+            servicePath:         this.servicePathValue,
+            apiKey:              this.apiKeyValue,
+            defaultLocation:     this.defaultLocationValue,
+            from:                from,
+            hideDeliveryOptions: { door: true, office: false },
+            lang:                "rus",
+            currency:            "RUB",
+            onChoose:            (mode, tariff, office) => this._handleChoose(office)
+        }
+
+        if (goods.length > 0) {
+            widgetOptions.goods = goods
+        }
+
+        try {
+            this._widget = new window.CDEKWidget(widgetOptions)
+        } catch (err) {
+            this._showError(err && err.message ? err.message : "ошибка инициализации виджета")
+        }
+    }
+
+    _handleChoose(office) {
+        if (!office) return
+        const code     = office.code || ""
+        const name     = office.name || ""
+        const address  = office.address || office.address_full || ""
+        const cityCode = office.city_code || ""
+
+        setFieldValue(this.fieldCodeValue,     code)
+        setFieldValue(this.fieldNameValue,     name)
+        setFieldValue(this.fieldAddressValue,  address)
+        setFieldValue(this.fieldCityCodeValue, cityCode)
+
+        const label = name ? (code ? `${name} (${code})` : name) : "не выбран"
+        setText(this.labelSelectorValue,   label)
+        setText(this.addressSelectorValue, address)
+
+        this.dispatch("chosen", { detail: { office } })
+        if (this.modalIdValue) {
+            document.dispatchEvent(new CustomEvent("modal:close", { detail: { id: this.modalIdValue } }))
+        }
+    }
+
+    _showError(message) {
+        if (this.hasErrorTarget) {
+            this.errorTarget.textContent = `Не удалось открыть виджет СДЭК: ${message}.`
+            this.errorTarget.style.display = ""
+        }
+        if (this.hasRootTarget) {
+            this.rootTarget.style.display = "none"
+        }
+    }
+}

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: cdek
+version: !ruby/object:Gem::Version
+  version: 0.3.9
+platform: ruby
+authors:
+- Your Name
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: 'Тонкий клиент для CDEK API v2 без внешних рантайм-зависимостей: конфигурация,
+  иерархия ошибок, автоматическое управление OAuth2-токеном. Поверх клиента — монтируемый
+  Rails Engine с прокси-эндпоинтом, вендорным JS-виджетом ПВЗ и Stimulus-контроллером.'
+email:
+- you@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- app/assets/javascripts/cdek/widget.umd.js
+- app/controllers/cdek/widget_service_controller.rb
+- app/helpers/cdek/widget_helper.rb
+- cdek.gemspec
+- config/routes.rb
+- lib/cdek.rb
+- lib/cdek/client.rb
+- lib/cdek/configuration.rb
+- lib/cdek/connection.rb
+- lib/cdek/engine.rb
+- lib/cdek/error.rb
+- lib/cdek/railtie.rb
+- lib/cdek/resources/base.rb
+- lib/cdek/resources/deliverypoints.rb
+- lib/cdek/resources/locations.rb
+- lib/cdek/version.rb
+- lib/generators/cdek/install/install_generator.rb
+- lib/generators/cdek/install/templates/cdek.rb
+- lib/generators/cdek/install/templates/cdek_widget_controller.js
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Ruby/Rails клиент и Engine для CDEK API v2 с виджетом ПВЗ
+test_files: []