dadata-rb 3.0.0

data/lib/dadata/api_exceptions.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Dadata
+  # Базовый класс обработки ошибок
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  # Raised when the API responds with a non-success HTTP status.
+  class ApiError < Error
+    attr_reader :status
+
+    def initialize(status, message)
+      @status = status
+      super("Error: #{status} - #{message}")
+    end
+  end
+
+  # Raised when the request never reaches a usable response (network failure).
+  # Carries its message through StandardError, so `raise ConnectionError, 'msg'` works.
+  class ConnectionError < Error; end
+
+  # Raised when the request exceeds the configured timeout. A ConnectionError so
+  # callers that rescue ConnectionError keep working; rescue TimeoutError first
+  # when distinct handling is needed.
+  class TimeoutError < ConnectionError; end
+
+  # Status-specific API errors. The HTTP status => class mapping lives in
+  # Dadata::ClientBase::STATUS_ERRORS (400, 401, 403, 404, 429 respectively).
+  class BadRequestError < ApiError; end
+  class UnauthorizedError < ApiError; end
+  class AuthenticationError < ApiError; end
+  class NotFoundError < ApiError; end
+  class RateLimitError < ApiError; end
+end

data/lib/dadata/client/base.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/retry'
+require 'json'
+require_relative '../sensitive_data'
+
+module Dadata
+  # Faraday middleware that handles logging of requests and responses while ensuring
+  # sensitive data is properly sanitized. This middleware is automatically added to
+  # all DaData API clients.
+  #
+  # @api private
+  class SensitiveDataMiddleware < Faraday::Middleware
+    include SensitiveData
+
+    # Processes the request, logs it securely, and handles any errors
+    #
+    # @param env [Hash] The request environment
+    # @return [Faraday::Response] The response from the next middleware
+    def call(env)
+      log_request(env)
+      @app.call(env).on_complete do |response_env|
+        log_response(response_env)
+      end
+    rescue Faraday::Error => e
+      log_error(e)
+      raise
+    end
+
+    private
+
+    # Logs the request details with sensitive data filtered
+    #
+    # @param env [Hash] The request environment
+    # @return [void]
+    def log_request(env)
+      return unless logger
+
+      logger.debug do
+        msg = "DaData Request: #{env.method.upcase} #{env.url}"
+        msg += "\nBody: #{request_body(env)}" if log_bodies? && request_body(env)
+        msg += "\nHeaders: #{sanitize_headers(env.request_headers)}"
+        msg
+      end
+    end
+
+    # Returns the request payload (POST body or GET params) for logging, or nil
+    # when there is nothing to log. Only consulted when body logging is enabled.
+    #
+    # @param env [Hash] The request environment
+    # @return [String, nil]
+    def request_body(env)
+      body = env.body
+      return body if body && !body.empty?
+
+      params = env.params
+      params.inspect if params && !params.empty?
+    end
+
+    # Whether request payloads may be logged. Off by default because payloads
+    # contain personal data this API processes.
+    #
+    # @return [Boolean]
+    def log_bodies?
+      Dadata.configuration&.log_request_bodies || false
+    end
+
+    # Logs the response details with sensitive data filtered
+    #
+    # @param env [Hash] The response environment
+    # @return [void]
+    def log_response(env)
+      return unless logger
+
+      logger.debug do
+        msg = "DaData Response: #{env.status}"
+        msg += "\nHeaders: #{sanitize_headers(env.response_headers)}"
+        msg
+      end
+    end
+
+    # Logs error details with sensitive data filtered
+    #
+    # @param error [Faraday::Error] The error that occurred
+    # @return [void]
+    def log_error(error)
+      return unless logger
+
+      logger.error do
+        msg = "DaData Error: #{error.class.name}"
+        msg += "\nMessage: #{sanitize_message(error.message)}"
+        msg += "\nHeaders: #{sanitize_headers(error.response[:response_headers] || {})}" if error.response
+        msg
+      end
+    end
+
+    # Gets the logger from the DaData configuration
+    #
+    # @return [Logger, nil] The configured logger
+    def logger
+      Dadata.configuration&.logger
+    end
+  end
+
+  # Base client class that handles HTTP communication with the DaData API.
+  # Implements secure logging and request/response handling.
+  #
+  # @api private
+  class ClientBase
+    include SensitiveData
+
+    # HTTP status codes and their descriptions
+    ERRORS = {
+      200 => 'Request processed successfully',
+      400 => 'Invalid request (invalid JSON or XML)',
+      401 => 'Missing API key or secret key, or non-existent key used',
+      403 => 'Invalid API key, unconfirmed email, or daily request limit exceeded',
+      404 => 'Service not found',
+      405 => 'Request method other than POST used',
+      413 => 'Request too long or too many conditions',
+      429 => 'Too many requests per second or new connections per minute',
+      500 => 'Internal service error'
+    }.freeze
+
+    # Maps HTTP status codes to the specific error class to raise.
+    # Any status not listed falls back to the generic ApiError.
+    STATUS_ERRORS = {
+      400 => BadRequestError,
+      401 => UnauthorizedError,
+      403 => AuthenticationError,
+      404 => NotFoundError,
+      429 => RateLimitError
+    }.freeze
+
+    # Creates a new client instance
+    #
+    # @param base_url [String] The base URL for API requests
+    # @param token [String] The API token for authentication
+    # @param secret [String, nil] Optional secret key for additional authentication
+    def initialize(base_url, token, secret = nil)
+      @base_url = base_url
+      @token = token
+      @secret = secret
+      @connection = build_connection
+      @logger = Dadata.configuration&.logger
+    end
+
+    # Submits a request to the API
+    #
+    # @param url [String] The endpoint URL
+    # @param data [Hash] The request data
+    # @param method [Symbol] The HTTP method to use (:get or :post)
+    # @param timeout [Integer] Request timeout in seconds
+    # @return [Hash] The parsed response
+    # @raise [ApiError] If the API returns an error
+    # @raise [ConnectionError] If there's a network error
+    def submit(url, data, method = :get, timeout: Dadata.timeout_sec)
+      response = send_request(url, data, method, timeout)
+      handle_response(response)
+    rescue Faraday::Error => e
+      handle_connection_error(e)
+    end
+
+    # Closes the persistent connection, releasing any pooled sockets.
+    #
+    # @return [void]
+    def close
+      @connection.close if @connection.respond_to?(:close)
+    end
+
+    private
+
+    # Builds the Faraday connection with appropriate middleware and settings
+    #
+    # @return [Faraday::Connection]
+    def build_connection
+      require 'faraday/net_http_persistent'
+
+      Faraday.new(@base_url) do |conn|
+        conn.request :json
+        conn.request :retry, {
+          max:                 2,
+          interval:            0.05,
+          interval_randomness: 0.5,
+          backoff_factor:      2,
+          exceptions:          [
+            Faraday::ConnectionFailed,
+            Faraday::TimeoutError,
+            'Timeout::Error'
+          ]
+        }
+
+        conn.use SensitiveDataMiddleware
+
+        conn.response :json, content_type: /\bjson$/
+
+        conn.headers = {
+          'Content-Type'  => 'application/json',
+          'Accept'        => 'application/json',
+          'Authorization' => "Token #{@token}"
+        }
+        conn.headers['X-Secret'] = @secret if @secret
+
+        conn.adapter :net_http_persistent do |http|
+          http.read_timeout = Dadata.configuration&.timeout_sec || 10
+          http.open_timeout = Dadata.configuration&.timeout_sec || 10
+          http.write_timeout = Dadata.configuration&.timeout_sec || 10
+        end
+      end
+    end
+
+    # Sends a request to the API
+    #
+    # @param url [String] The endpoint URL
+    # @param data [Hash] The request data
+    # @param method [Symbol] The HTTP method to use (:get or :post)
+    # @param timeout [Integer] Request timeout in seconds
+    # @return [Faraday::Response] The response from the API
+    def send_request(url, data, method, timeout)
+      @connection.public_send(method) do |req|
+        req.url(url)
+        req.options.timeout = timeout
+        req.body = data.to_json unless method == :get
+        req.params = data if method == :get
+      end
+    end
+
+    # Handles the response from the API
+    #
+    # @param response [Faraday::Response] The response from the API
+    # @return [Hash] The parsed response
+    # @raise [ApiError] If the API returns an error
+    def handle_response(response)
+      return response.body if response.success?
+
+      error_message = ERRORS[response.status] || 'Unknown error'
+      log_error("API Error: #{error_message} (#{response.status})")
+
+      error_class = STATUS_ERRORS.fetch(response.status, ApiError)
+      raise error_class.new(response.status, error_message)
+    end
+
+    # Handles connection errors
+    #
+    # @param error [Faraday::Error] The error that occurred
+    # @raise [ConnectionError] If there's a network error
+    def handle_connection_error(error)
+      sanitized_error = sanitize_message(error.message)
+      log_error("Connection Error: #{sanitized_error}")
+      log_error("Headers: #{sanitize_headers(@connection.headers)}")
+
+      case error
+      when Faraday::TimeoutError
+        raise TimeoutError, 'Request timed out'
+      when Faraday::ConnectionFailed
+        raise ConnectionError, 'Failed to connect'
+      else
+        raise ConnectionError, 'Request failed'
+      end
+    end
+
+    # Logs an error, with sensitive data filtered. Sanitization comes from
+    # the shared SensitiveData module.
+    #
+    # @param message [String] The error message
+    # @return [void]
+    def log_error(message)
+      @logger&.error(sanitize_message(message))
+    end
+  end
+end

data/lib/dadata/client/clean.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Dadata
+  # Client for data cleaning and standardization operations
+  class CleanClient < ClientBase
+    BASE_URL = 'https://cleaner.dadata.ru/api/v1/'
+
+    def initialize(token = Dadata.api_key, secret = Dadata.secret_key)
+      super(BASE_URL, token, secret)
+    end
+
+    # Clean and standardize a single value
+    #
+    # @param name [String] Type of cleaning to apply:
+    #   - address - postal address
+    #   - phone - phone number
+    #   - passport - passport number
+    #   - name - full name
+    #   - email - email address
+    #   - birthdate - date
+    #   - vehicle - vehicle brand and model
+    #   - simple_party_name - company name
+    # @param source [String] Value to clean
+    # @return [Hash, nil] Cleaned data or nil if cleaning failed
+    def clean(name, source)
+      response = submit("clean/#{name}", [source], :post)
+      response&.first
+    end
+
+    # Clean and standardize a composite record
+    #
+    # @param structure [Array<String>] Record structure with fields:
+    #   - AS_IS - leave as is (no standardization)
+    #   - SIMPLE_PARTY_NAME - parse company name
+    #   - NAME - parse as full name
+    #   - BIRTHDATE - parse as date
+    #   - ADDRESS - parse as address
+    #   - PHONE - parse as phone
+    #   - PASSPORT - passport number
+    #   - EMAIL - email address
+    #   - VEHICLE - vehicle brand and model
+    # @param record [Array<String>] Record to process; field order must match structure
+    # @return [Hash, nil] Cleaned data or nil if cleaning failed
+    def clean_record(structure, record)
+      data = { structure:, data: [record] }
+      response = submit('clean', data, :post)
+      response&.dig('data', 0)
+    end
+  end
+end

data/lib/dadata/client/profile.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require 'date'
+
+module Dadata
+  # Client for managing DaData subscriber profile
+  class ProfileClient < ClientBase
+    BASE_URL = 'https://dadata.ru/api/v2/'
+
+    def initialize(token = Dadata.api_key, secret = Dadata.secret_key)
+      super(BASE_URL, token, secret)
+    end
+
+    # Get current balance
+    #
+    # @return [Numeric, nil] Current balance or nil if request failed
+    def balance
+      response = submit('profile/balance', {}, :get)
+      response&.fetch('balance', nil)
+    end
+
+    # Get daily statistics
+    #
+    # @param date [String, nil] Date to get statistics for (ISO 8601 format)
+    # @return [Hash, nil] Daily statistics or nil if request failed
+    def daily_stats(date = nil)
+      date = date.nil? ? Date.today : handle_date(date)
+      submit('stat/daily', { date: date.iso8601 }, :get)
+    end
+
+    # Get API versions
+    #
+    # @return [Hash, nil] Version information or nil if request failed
+    def versions
+      submit('version', {}, :get)
+    end
+
+    private
+
+    # Convert string to Date object
+    #
+    # @param date_string [String] Date string in any parseable format
+    # @return [Date] Parsed date or today's date if parsing fails
+    def handle_date(date_string)
+      Date.parse(date_string.to_s)
+    rescue ArgumentError, TypeError
+      Date.today
+    end
+  end
+end

data/lib/dadata/client/suggest.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Dadata
+  # Client for data suggestions and lookups
+  class SuggestClient < ClientBase
+    BASE_URL = 'https://suggestions.dadata.ru/suggestions/api/4_1/rs/'
+
+    def initialize(token = Dadata.api_key, secret = Dadata.secret_key)
+      super(BASE_URL, token, secret)
+    end
+
+    # Find addresses by geographic coordinates
+    #
+    # @param name [String] Type of entity to search for (e.g., 'address', 'postal_unit')
+    # @param lat [Numeric] Latitude
+    # @param lon [Numeric] Longitude
+    # @param radius_meters [Integer] Search radius in meters (default: 100, max: 1000)
+    # @param kwargs [Hash] Additional parameters (e.g., language, count)
+    # @return [Array<Hash>, nil] List of suggestions or nil if not found
+    def geolocate(name, lat, lon, radius_meters = 100, **kwargs)
+      data = { lat:, lon:, radius_meters: }.merge(kwargs)
+      response = submit("geolocate/#{name}", data, :post)
+      response&.fetch('suggestions', nil)
+    end
+
+    # Get address by IP
+    #
+    # @param query [String] IP address
+    # @param kwargs [Hash] Additional parameters (e.g., language)
+    # @return [Hash, nil] Location data or nil if not found
+    def iplocate(query, **kwargs)
+      data = { ip: query }.merge(kwargs)
+      response = submit('iplocate/address', data, :get)
+      response&.fetch('location', nil)
+    end
+
+    # Get suggestions for partial input
+    #
+    # @param name [String] Type of entity to search for
+    # @param query [String] Search query
+    # @param count [Integer] Maximum number of results
+    # @param kwargs [Hash] Additional parameters (e.g., language, constraints)
+    # @return [Array<Hash>, nil] List of suggestions or nil if not found
+    def suggest(name, query, count = Dadata.suggestions_count, **kwargs)
+      data = { query:, count: }.merge(kwargs)
+      response = submit("suggest/#{name}", data, :post)
+      response&.fetch('suggestions', nil)
+    end
+
+    # Find entities by identifier
+    #
+    # @param name [String] Type of entity to search for
+    # @param query [String] Entity identifier
+    # @param count [Integer] Maximum number of results
+    # @param kwargs [Hash] Additional parameters (e.g., language)
+    # @return [Array<Hash>, nil] List of suggestions or nil if not found
+    def find_by_id(name, query, count = Dadata.suggestions_count, **kwargs)
+      data = { query:, count: }.merge(kwargs)
+      response = submit("findById/#{name}", data, :post)
+      response&.fetch('suggestions', nil)
+    end
+
+    # Find companies by email address
+    #
+    # @param query [String] Email address
+    # @return [Array<Hash>, nil] List of companies or nil if not found
+    def find_by_email(query)
+      response = submit('findByEmail/company', { query: }, :post)
+      response&.fetch('suggestions', nil)
+    end
+
+    # Find affiliated companies
+    #
+    # @param query [String] Company identifier
+    # @param count [Integer] Maximum number of results
+    # @param kwargs [Hash] Additional parameters (e.g., scope, type)
+    # @return [Array<Hash>, nil] List of affiliated companies or nil if not found
+    def find_affiliated(query, count = Dadata.suggestions_count, **kwargs)
+      data = { query:, count: }.merge(kwargs)
+      response = submit('findAffiliated/party', data, :post)
+      response&.fetch('suggestions', nil)
+    end
+  end
+end

data/lib/dadata/sensitive_data.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Dadata
+  # The SensitiveData module provides functionality for sanitizing sensitive information
+  # in log messages and HTTP headers. It is used internally by the gem to ensure that
+  # sensitive data such as API keys and secrets are not exposed in logs.
+  #
+  # @example
+  #   class MyLogger
+  #     include SensitiveData
+  #
+  #     def log_request(headers)
+  #       puts sanitize_headers(headers)
+  #     end
+  #   end
+  module SensitiveData
+    # List of headers that contain sensitive information and should be filtered
+    SENSITIVE_HEADERS = %w[Authorization X-Secret API-Key].freeze
+
+    # Sanitizes headers by replacing sensitive values with [FILTERED]
+    #
+    # @param headers [Hash, nil] Headers to sanitize
+    # @return [String] Sanitized headers string
+    # @example
+    #   headers = { 'API-Key' => 'secret', 'Content-Type' => 'application/json' }
+    #   sanitize_headers(headers) # => "API-Key: [FILTERED], Content-Type: application/json"
+    def sanitize_headers(headers)
+      return '' unless headers
+
+      headers.map do |key, value|
+        if SENSITIVE_HEADERS.include?(key)
+          "#{key}: [FILTERED]"
+        else
+          "#{key}: #{value}"
+        end
+      end.join(', ')
+    end
+
+    # Sanitizes a message by replacing sensitive information with [FILTERED]
+    #
+    # @param msg [String, nil] Message to sanitize
+    # @return [String] Sanitized message
+    # @example
+    #   msg = "API-Key: secret123, Content-Type: application/json"
+    #   sanitize_message(msg) # => "API-Key: [FILTERED], Content-Type: application/json"
+    def sanitize_message(msg)
+      return '' unless msg.is_a?(String)
+
+      result = msg.dup
+      SENSITIVE_HEADERS.each do |header|
+        # Escape hyphens in the header name and handle any whitespace around the colon
+        pattern = /#{Regexp.escape(header)}[\s]*:[\s]*[^\n,]+/
+        result = result.gsub(pattern, "#{header}: [FILTERED]")
+      end
+      result
+    end
+  end
+end

data/lib/dadata/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Dadata
+  VERSION = '3.0.0'
+end

data/lib/dadata-rb.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Lets `require 'dadata-rb'` (the published gem name) load the library, whose
+# entry point and `Dadata` module live in `dadata.rb`. This keeps Bundler's
+# default auto-require working for consumers who add `gem 'dadata-rb'`.
+require_relative 'dadata'