cdek 0.3.10 → 0.3.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6463b54566dc996e5be0cdd477b9d82351d13fa656fcaa69cd616316ae1f383
-  data.tar.gz: 61bf32c28513536ebbf227f748eba6a9d86a5498ed03f3f9484cac3f03bb974a
+  metadata.gz: 7c67295d1a6a2b9199d0c751a230ab6dc48ecda34fe855ec74eca1276efccf05
+  data.tar.gz: f43d4696e5f063d284329a2fb34fed6f9775807a2a79490623b7f1b6d0ef7526
 SHA512:
-  metadata.gz: ac67d9d0ef2bc0bfc0fc7867956665a912405d4083a2a949be13c3debfc76c8c54e8fc572929c44c701b006866dbbdae9106f3d788232a30a7ebbaff8a8c18e1
-  data.tar.gz: a9fc17a09adb1410247373d28afd0ab96793f9c52668f5668e12f752b5a88379ab64f0565901dc219753446588d9e57d0c735b7a82e6d0e849472b85fd246ffa
+  metadata.gz: 6ffcc0ddbfc9046c56bcc24246922a8755b492f8932d267298602dd7a49bcc447c88f2400ae562214759ff52441855889f67dd9508b7e56e50a7e4cdf11666c1
+  data.tar.gz: d6b4f68d0f9d992fb22b34f6c31298a0394b08072ae4165414f735d7586dff05e36d54b06e86cd65fd68040d62f8742109780a8fbad2d9c4a2a67a22edf9d4aa

data/README.md

@@ -6,6 +6,7 @@
 * OAuth2 client_credentials c потокобезопасным кэшем токена.
 * Конфигурация через ENV или Rails-инициализатор.
 * High-level ресурсы для частых задач: `Cdek.locations`, `Cdek.deliverypoints`.
+* Поиск CDEK-кода города и JSON-подсказки городов для autocomplete.
 * **Rails Engine** с прокси-эндпоинтом для официального JS-виджета ПВЗ
   (cdek-it/widget@3).
 * Вендорный UMD-бандл виджета — раздаётся через asset pipeline (без CDN).
@@ -62,6 +63,10 @@ Cdek.client.get("/deliverypoints", params: { city_code: 44, type: "PVZ" })
 # High-level:
 moscow = Cdek.locations.find_city("Москва")
 points = Cdek.deliverypoints.pvz_for_city(moscow.fetch("code"))
+
+# Город по пользовательскому вводу:
+city_code = Cdek.city_code("Москва")
+suggestions = Cdek.city_suggestions("мос")
 ```
 
 ## Виджет ПВЗ
@@ -98,7 +103,11 @@ points = Cdek.deliverypoints.pvz_for_city(moscow.fetch("code"))
 2. JS-контроллер `cdek-widget` (поставлен генератором) подгружает
    `/assets/cdek/widget.umd.js` (вшитый в гем UMD-бандл) и инициализирует
    `window.CDEKWidget` в root-таргете.
-3. Виджет шлёт запросы на `/cdek/widget_service` (Engine route).
+3. Виджет шлёт запросы на `/cdek/widget_service` (Engine route). Если
+   `default_city` передан строкой, Stimulus-контроллер добавляет к servicePath
+   внутренний параметр `widget_city`, а Engine преобразует его в `city_code`
+   перед запросом `/deliverypoints`. Это не даёт виджету загружать все ПВЗ
+   страны при открытии карты.
 4. На `onChoose` контроллер пишет данные выбранного пункта в скрытые поля
    формы — по умолчанию:
 
@@ -113,6 +122,18 @@ points = Cdek.deliverypoints.pvz_for_city(moscow.fetch("code"))
 5. Также диспатчится событие `cdek-widget:chosen` с `detail.office` —
    можно слушать в собственных Stimulus-контроллерах.
 
+### Подсказки городов
+
+Engine предоставляет read-only JSON endpoint для autocomplete:
+
+```text
+GET /cdek/city_suggestions?q=мос
+```
+
+Ответ — массив нормализованных объектов с `code`, `city`, `region`,
+`country`, `country_code` и готовым `label`. UI поля ввода, debounce и
+выпадающий список остаются на стороне хост-приложения.
+
 ### Закрытие модалки
 
 Если виджет встроен в модалку, передайте её `id` в `modal_id:` — после

data/app/controllers/cdek/city_suggestions_controller.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Cdek
+  # Public read-only endpoint for city autocomplete in host applications.
+  class CitySuggestionsController < ::ActionController::Base
+    def index
+      render json: Cdek.city_suggestions(
+        params[:q],
+        country_code: params[:country_code].presence || Cdek::CitySuggestions::DEFAULT_COUNTRY_CODE
+      )
+    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
+  end
+end

data/app/controllers/cdek/widget_service_controller.rb

@@ -38,6 +38,11 @@ module Cdek
     EXCLUDED_PARAM_KEYS = %w[action controller format].freeze
     private_constant :EXCLUDED_PARAM_KEYS
 
+    # Дополнительный параметр engine'а: хост-приложение может передать
+    # пользовательский город текстом, а gem преобразует его в city_code CDEK.
+    WIDGET_CITY_KEY = "widget_city"
+    private_constant :WIDGET_CITY_KEY
+
     def call
       cdek_action = cdek_request_action
 
@@ -67,12 +72,26 @@ module Cdek
       end
 
       # Все параметры запроса, кроме служебных Rails-роутинга и Rails-обёртки.
-      # Передаются в CDEK API как есть.
+      # Передаются в CDEK API как есть, кроме widget_city: это внутренний
+      # параметр engine'а, который нормализуется в CDEK city_code.
       def cdek_filtered_params
-        request.query_parameters
-               .merge(request.request_parameters)
-               .except(*EXCLUDED_PARAM_KEYS, WRAPPER_KEY)
-               .to_h
+        raw_params = request.query_parameters
+                            .merge(request.request_parameters)
+                            .except(*EXCLUDED_PARAM_KEYS, WRAPPER_KEY)
+                            .to_h
+
+        cdek_params_with_city_code(raw_params)
+      end
+
+      def cdek_params_with_city_code(raw_params)
+        params = raw_params.except(WIDGET_CITY_KEY)
+        city_code = raw_params["city_code"].presence || Cdek.city_code(raw_params[WIDGET_CITY_KEY])
+
+        if city_code.present?
+          params.merge("city_code" => city_code).compact
+        else
+          params.compact
+        end
       end
   end
 end

data/config/routes.rb

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

data/lib/cdek/city_resolver.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Cdek
+  # Resolves a human-readable city name to a CDEK city code.
+  #
+  # This is intentionally small and API-backed: host applications can pass
+  # user-entered city names to the widget proxy without duplicating lookup
+  # logic or loading all delivery points for the whole country.
+  class CityResolver
+    DEFAULT_COUNTRY_CODES = "RU"
+    CACHE_EXPIRES_IN = 43_200
+
+    class << self
+      def call(name, **options)
+        new(name, **options).call
+      end
+    end
+
+    def initialize(name, client: Cdek.client, country_codes: DEFAULT_COUNTRY_CODES, cache: default_cache)
+      @name = name
+      @client = client
+      @country_codes = country_codes
+      @cache = cache
+    end
+
+    def call
+      normalized_name.empty? ? nil : cached_city_code
+    end
+
+    private
+
+      attr_reader :name, :client, :country_codes, :cache
+
+      def cached_city_code
+        if cache
+          cache.fetch(cache_key, expires_in: CACHE_EXPIRES_IN) { fetch_city_code }
+        else
+          fetch_city_code
+        end
+      end
+
+      def fetch_city_code
+        city = Cdek.locations(client).find_city(normalized_name, country_codes: country_codes)
+
+        if city.is_a?(Hash)
+          city["code"] || city[:code]
+        end
+      end
+
+      def normalized_name
+        @normalized_name ||= name.to_s.strip
+      end
+
+      def cache_key
+        ["cdek", "city_code", country_codes, normalized_name.downcase].join(":")
+      end
+
+      def default_cache
+        if defined?(::Rails) && ::Rails.respond_to?(:cache)
+          ::Rails.cache
+        end
+      end
+  end
+end

data/lib/cdek/city_suggestions.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Cdek
+  # Builds normalized city suggestions for host application autocomplete UIs.
+  class CitySuggestions
+    DEFAULT_COUNTRY_CODE = "RU"
+    DEFAULT_LIMIT = 10
+    MIN_QUERY_LENGTH = 2
+
+    class << self
+      def call(query, **options)
+        new(query, **options).call
+      end
+    end
+
+    def initialize(query, client: Cdek.client, country_code: DEFAULT_COUNTRY_CODE, limit: DEFAULT_LIMIT)
+      @query = query
+      @client = client
+      @country_code = country_code
+      @limit = limit
+    end
+
+    def call
+      normalized_query.length < MIN_QUERY_LENGTH ? [] : normalized_suggestions
+    end
+
+    private
+
+      attr_reader :query, :client, :country_code, :limit
+
+      def normalized_suggestions
+        Array(raw_suggestions).first(limit).filter_map do |city|
+          suggestion_payload(city)
+        end
+      end
+
+      def raw_suggestions
+        Cdek.locations(client).suggest_cities(name: normalized_query, country_code: country_code)
+      end
+
+      def suggestion_payload(city)
+        if city.is_a?(Hash)
+          code = city["code"] || city[:code]
+          city_name = city["city"] || city[:city] || city["name"] || city[:name]
+          region = city["region"] || city[:region]
+          country = city["country"] || city[:country]
+          country_code_value = city["country_code"] || city[:country_code]
+
+          if code && city_name
+            {
+              code: code,
+              city: city_name,
+              region: region,
+              country: country,
+              country_code: country_code_value,
+              label: label_for(city_name, region)
+            }
+          end
+        end
+      end
+
+      def label_for(city_name, region)
+        [city_name, region].compact.map(&:to_s).reject(&:empty?).uniq.join(", ")
+      end
+
+      def normalized_query
+        @normalized_query ||= query.to_s.strip
+      end
+  end
+end

data/lib/cdek/version.rb

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

data/lib/cdek.rb

@@ -8,6 +8,8 @@ require "cdek/client"
 require "cdek/resources/base"
 require "cdek/resources/locations"
 require "cdek/resources/deliverypoints"
+require "cdek/city_resolver"
+require "cdek/city_suggestions"
 
 module Cdek
   CLIENT_MUTEX = Mutex.new
@@ -60,6 +62,16 @@ module Cdek
     def deliverypoints(custom_client = client)
       Resources::Deliverypoints.new(custom_client)
     end
+
+    # CDEK-код города по пользовательскому названию.
+    def city_code(name, **options)
+      CityResolver.call(name, **options)
+    end
+
+    # Нормализованные подсказки городов для autocomplete в хост-приложении.
+    def city_suggestions(query, **options)
+      CitySuggestions.call(query, **options)
+    end
   end
 end
 

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

@@ -90,12 +90,16 @@ export default class extends Controller {
     }
 
     connect() {
-        ensureWidgetScript(this.scriptUrlValue)
-            .then(() => this._mountWidget())
-            .catch((err) => this._showError(err && err.message ? err.message : "ошибка"))
+        this._connected = true
+        this._mountWhenReady()
     }
 
     disconnect() {
+        this._connected = false
+        if (this._mountTimer) {
+            window.clearTimeout(this._mountTimer)
+            this._mountTimer = null
+        }
         if (this._widget) {
             try {
                 if (typeof this._widget.destroy === "function") this._widget.destroy()
@@ -105,6 +109,35 @@ export default class extends Controller {
         }
     }
 
+    _mountWhenReady() {
+        if (!this._connected || this._widget || this._mounting) return
+        if (!this._isRootVisible()) {
+            this._mountTimer = window.setTimeout(() => this._mountWhenReady(), 50)
+            return
+        }
+
+        this._mounting = true
+        ensureWidgetScript(this.scriptUrlValue)
+            .then(() => this._mountWidget())
+            .catch((err) => this._showError(err && err.message ? err.message : "ошибка"))
+            .finally(() => { this._mounting = false })
+    }
+
+    _isRootVisible() {
+        if (!this.hasRootTarget) return false
+        const rect = this.rootTarget.getBoundingClientRect()
+        return rect.width > 0 && rect.height > 0
+    }
+
+    _servicePath() {
+        const url = new URL(this.servicePathValue, window.location.origin)
+        const widgetCity = this.defaultLocationValue.trim()
+        if (widgetCity !== "") {
+            url.searchParams.set("widget_city", widgetCity)
+        }
+        return url.pathname + url.search
+    }
+
     _mountWidget() {
         if (!this.hasRootTarget) return
         if (typeof window.CDEKWidget !== "function") {
@@ -129,7 +162,7 @@ export default class extends Controller {
         const goods = parseGoods(this.goodsValue)
         const widgetOptions = {
             root:                this.rootTarget.id,
-            servicePath:         this.servicePathValue,
+            servicePath:         this._servicePath(),
             apiKey:              this.apiKeyValue,
             defaultLocation:     this.defaultLocationValue,
             from:                from,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cdek
 version: !ruby/object:Gem::Version
-  version: 0.3.10
+  version: 0.3.11
 platform: ruby
 authors:
 - Sergey Korolyov
@@ -36,11 +36,14 @@ files:
 - LICENSE
 - README.md
 - app/assets/javascripts/cdek/widget.umd.js
+- app/controllers/cdek/city_suggestions_controller.rb
 - app/controllers/cdek/widget_service_controller.rb
 - app/helpers/cdek/widget_helper.rb
 - cdek.gemspec
 - config/routes.rb
 - lib/cdek.rb
+- lib/cdek/city_resolver.rb
+- lib/cdek/city_suggestions.rb
 - lib/cdek/client.rb
 - lib/cdek/configuration.rb
 - lib/cdek/connection.rb