yookassarb 0.1.0

data/lib/yookassa/entities/payment.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Yookassa
+  module Entities
+    # Payment entity with status helpers and confirmation URL access.
+    #
+    # All attributes from the API response (id, status, amount, description, etc.)
+    # are accessible as methods via the inherited {Base} dynamic dispatch.
+    #
+    # @see https://yookassa.ru/developers/api#payment_object Payment object reference
+    class Payment < Base
+      # Returns the confirmation URL for redirect-based payment flows.
+      #
+      # @return [String, nil] the URL to redirect the user to, or +nil+ if not available
+      def confirmation_url
+        return nil unless attributes["confirmation"]
+
+        attributes.dig("confirmation", "confirmation_url")
+      end
+
+      # @return [Boolean] +true+ if the payment completed successfully
+      def succeeded?
+        status == "succeeded"
+      end
+
+      # @return [Boolean] +true+ if the payment is awaiting user action
+      def pending?
+        status == "pending"
+      end
+
+      # @return [Boolean] +true+ if the payment was canceled
+      def canceled?
+        status == "canceled"
+      end
+
+      # @return [Boolean] +true+ if the payment is authorized and awaiting capture
+      def waiting_for_capture?
+        status == "waiting_for_capture"
+      end
+    end
+  end
+end

data/lib/yookassa/entities/payout.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Yookassa
+  module Entities
+    # Payout entity with status helpers.
+    #
+    # @see https://yookassa.ru/developers/api#payout_object Payout object reference
+    class Payout < Base
+      # @return [Boolean] +true+ if the payout completed successfully
+      def succeeded?
+        status == "succeeded"
+      end
+
+      # @return [Boolean] +true+ if the payout was canceled
+      def canceled?
+        status == "canceled"
+      end
+    end
+  end
+end

data/lib/yookassa/entities/receipt.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Yookassa
+  module Entities
+    # Receipt entity with status helpers.
+    #
+    # @see https://yookassa.ru/developers/api#receipt_object Receipt object reference
+    class Receipt < Base
+      # @return [Boolean] +true+ if the receipt was delivered successfully
+      def succeeded?
+        status == "succeeded"
+      end
+    end
+  end
+end

data/lib/yookassa/entities/refund.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Yookassa
+  module Entities
+    # Refund entity with status helpers.
+    #
+    # @see https://yookassa.ru/developers/api#refund_object Refund object reference
+    class Refund < Base
+      # @return [Boolean] +true+ if the refund completed successfully
+      def succeeded?
+        status == "succeeded"
+      end
+
+      # @return [Boolean] +true+ if the refund was canceled
+      def canceled?
+        status == "canceled"
+      end
+    end
+  end
+end

data/lib/yookassa/entities/webhook_obj.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Yookassa
+  module Entities
+    # Webhook subscription entity representing a registered webhook endpoint.
+    #
+    # @see https://yookassa.ru/developers/api#webhook_object Webhook object reference
+    class WebhookObj < Base
+    end
+  end
+end

data/lib/yookassa/errors.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Yookassa
+  # Base error class for all YooKassa gem errors.
+  class Error < StandardError; end
+
+  # Error returned by the YooKassa API with structured details.
+  #
+  # @example Handling an API error
+  #   begin
+  #     Yookassa::Payment.find("nonexistent")
+  #   rescue Yookassa::ApiError => e
+  #     puts e.code          # => "not_found"
+  #     puts e.http_code     # => 404
+  #     puts e.description   # => "Payment not found"
+  #   end
+  class ApiError < Error
+    # @return [String, nil] YooKassa error code (e.g. "invalid_request", "not_found")
+    attr_reader :code
+
+    # @return [String, nil] human-readable error description
+    attr_reader :description
+
+    # @return [String, nil] name of the invalid parameter, if applicable
+    attr_reader :parameter
+
+    # @return [Hash] raw response details (:http_code, :body, :headers)
+    attr_reader :response
+
+    # @param code [String, nil] YooKassa error code
+    # @param description [String, nil] error description
+    # @param parameter [String, nil] invalid parameter name
+    # @param response [Hash] raw HTTP response info
+    def initialize(code: nil, description: nil, parameter: nil, response: {})
+      @code = code
+      @description = description
+      @parameter = parameter
+      @response = response
+      super(description || "API error (HTTP #{http_code})")
+    end
+
+    # @return [Integer, nil] HTTP status code
+    def http_code
+      @response[:http_code]
+    end
+
+    # @return [String, nil] raw response body
+    def response_body
+      @response[:body]
+    end
+
+    # @return [Hash, nil] response headers
+    def response_headers
+      @response[:headers]
+    end
+  end
+
+  # Raised when API returns 400 Bad Request.
+  class BadRequestError < ApiError; end
+
+  # Raised when API returns 401 Unauthorized.
+  class UnauthorizedError < ApiError; end
+
+  # Raised when API returns 403 Forbidden.
+  class ForbiddenError < ApiError; end
+
+  # Raised when API returns 404 Not Found.
+  class NotFoundError < ApiError; end
+
+  # Raised when API returns 429 Too Many Requests.
+  class TooManyRequestsError < ApiError; end
+
+  # Raised when API returns 500 Internal Server Error.
+  class InternalServerError < ApiError; end
+
+  # Raised when network connection fails.
+  class ConnectionError < Error; end
+
+  # Raised when request times out.
+  class TimeoutError < ConnectionError; end
+end

data/lib/yookassa/middleware/error_handler.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Yookassa
+  module Middleware
+    # Faraday middleware that maps HTTP error responses to typed exceptions.
+    #
+    # Inspects the response status and raises the appropriate {ApiError} subclass.
+    # The error body is parsed to extract YooKassa error code, description,
+    # and parameter name when available.
+    #
+    # @see Yookassa::ApiError
+    class ErrorHandler < Faraday::Middleware
+      # Maps HTTP status codes to error classes.
+      ERROR_MAP = {
+        400 => Yookassa::BadRequestError,
+        401 => Yookassa::UnauthorizedError,
+        403 => Yookassa::ForbiddenError,
+        404 => Yookassa::NotFoundError,
+        429 => Yookassa::TooManyRequestsError,
+        500 => Yookassa::InternalServerError
+      }.freeze
+
+      def on_complete(env)
+        return if env.success?
+
+        status = env.status
+        body = env.body
+        error_class = ERROR_MAP[status] || Yookassa::ApiError
+        error_data = parse_error_body(body)
+
+        raise error_class.new(
+          code: error_data[:code],
+          description: error_data[:description],
+          parameter: error_data[:parameter],
+          response: {
+            http_code: status,
+            body: body,
+            headers: env.response_headers
+          }
+        )
+      end
+
+      private
+
+      def parse_error_body(body)
+        return {} if body.to_s.empty?
+
+        parsed = JSON.parse(body)
+        {
+          code: parsed["code"],
+          description: parsed["description"],
+          parameter: parsed["parameter"]
+        }
+      rescue JSON::ParserError
+        { description: body }
+      end
+    end
+  end
+end

data/lib/yookassa/middleware/idempotency.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Yookassa
+  module Middleware
+    # Faraday middleware that ensures POST and DELETE requests include an idempotency key.
+    #
+    # If the +Idempotence-Key+ header is not already set, a UUID v4 is generated
+    # automatically. This prevents duplicate operations when requests are retried.
+    class Idempotency < Faraday::Middleware
+      # YooKassa idempotency header name.
+      IDEMPOTENCY_HEADER = "Idempotence-Key"
+
+      # @param app [#call] the next middleware in the Faraday stack
+      # @param idempotency_key [String, nil] optional fixed key (mainly for testing)
+      def initialize(app, idempotency_key: nil)
+        super(app)
+        @idempotency_key = idempotency_key
+      end
+
+      def on_request(env)
+        return unless %i[post delete].include?(env.method)
+
+        headers = env.request_headers
+        return if headers[IDEMPOTENCY_HEADER]
+
+        headers[IDEMPOTENCY_HEADER] = @idempotency_key || SecureRandom.uuid
+      end
+    end
+  end
+end

data/lib/yookassa/middleware/retry.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Yookassa
+  module Middleware
+    # Faraday middleware that retries requests on transient failures.
+    #
+    # Retries on HTTP 202 (object not ready yet), 500 (server error),
+    # and Faraday connection/timeout exceptions. Uses linear backoff
+    # with configurable delay.
+    class Retry < Faraday::Middleware
+      # HTTP status codes that trigger a retry.
+      RETRYABLE_STATUSES = [202, 500].freeze
+
+      # @param app [#call] the next middleware in the Faraday stack
+      # @param max_retries [Integer] maximum number of retry attempts (default: 3)
+      # @param retry_delay [Float] base delay in seconds, multiplied by attempt number (default: 1.8)
+      def initialize(app, max_retries: 3, retry_delay: 1.8)
+        super(app)
+        @max_retries = max_retries
+        @retry_delay = retry_delay
+      end
+
+      def call(env)
+        attempt = 0
+
+        loop do
+          response = @app.call(env)
+          return response unless retryable_status?(response, attempt)
+
+          attempt = prepare_retry(attempt, env)
+        rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+          raise e if attempt >= @max_retries
+
+          attempt = prepare_retry(attempt, env)
+        end
+      end
+
+      private
+
+      def retryable_status?(response, attempt)
+        RETRYABLE_STATUSES.include?(response.status) && attempt < @max_retries
+      end
+
+      def prepare_retry(attempt, env)
+        attempt += 1
+        wait(attempt)
+        env.body = env.request_body
+        attempt
+      end
+
+      def wait(attempt)
+        sleep(@retry_delay * attempt)
+      end
+    end
+  end
+end

data/lib/yookassa/resources/base.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module Yookassa
+  module Resources
+    # Base resource class with HTTP request handling and Faraday connection setup.
+    #
+    # Subclasses declare +resource_path+ and +entity_class+ to inherit default
+    # +create+, +find+, and +list+ behaviour. Resources that need custom logic
+    # (e.g. {Payment}) override those methods directly.
+    #
+    # @abstract Subclass and declare +resource_path+ / +entity_class+
+    class Base
+      # @return [Client] the API client this resource belongs to
+      attr_reader :client
+
+      # @param client [Client] the API client instance
+      def initialize(client)
+        @client = client
+      end
+
+      # Declares or retrieves the API path for this resource.
+      #
+      # @param path [String, nil] the API path (e.g. "payments") when setting
+      # @return [String, nil] the configured path
+      def self.resource_path(path = nil)
+        if path
+          @resource_path = path
+        else
+          @resource_path
+        end
+      end
+
+      # Declares or retrieves the entity class for wrapping API responses.
+      #
+      # @param klass [Class, nil] the entity class when setting
+      # @return [Class, nil] the configured entity class
+      def self.entity_class(klass = nil)
+        if klass
+          @entity_class = klass
+        else
+          @entity_class
+        end
+      end
+
+      # Creates a new resource via POST.
+      #
+      # @param params [Hash] resource attributes
+      # @param idempotency_key [String, nil] optional idempotency key
+      # @return [Entities::Base] the created entity
+      # @raise [ApiError] on API failure
+      def create(params, idempotency_key: nil)
+        data = request(:post, resource_path, body: params, idempotency_key: idempotency_key)
+        entity_class.new(data)
+      end
+
+      # Retrieves a single resource by ID via GET.
+      #
+      # @param resource_id [String] the resource identifier
+      # @return [Entities::Base] the found entity
+      # @raise [NotFoundError] if resource does not exist
+      def find(resource_id)
+        data = request(:get, "#{resource_path}/#{resource_id}")
+        entity_class.new(data)
+      end
+
+      # Lists resources matching the given filters via GET.
+      #
+      # @param filters [Hash] query parameters (limit, cursor, status, etc.)
+      # @return [Entities::Collection] paginated collection of entities
+      def list(**filters)
+        build_collection(resource_path, entity_class: entity_class, query: filters)
+      end
+
+      private
+
+      def resource_path
+        self.class.resource_path
+      end
+
+      def entity_class
+        self.class.entity_class
+      end
+
+      def connection
+        @connection ||= build_connection
+      end
+
+      def request(method, path, body: nil, query: nil, idempotency_key: nil)
+        response = connection.public_send(method) do |req|
+          req.url path
+          req.params = query if query
+          req.body = JSON.generate(body) if body
+          req.headers["Idempotence-Key"] = idempotency_key if idempotency_key && %i[post delete].include?(method)
+        end
+
+        parse_response(response)
+      end
+
+      def parse_response(response)
+        body = response.body
+        return nil if body.to_s.empty?
+
+        JSON.parse(body)
+      end
+
+      def build_connection
+        Faraday.new(url: "https://api.yookassa.ru/v3") do |conn|
+          configure_headers(conn)
+          configure_auth(conn)
+          configure_middleware(conn)
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      def configure_headers(conn)
+        conn.request :json
+        headers = conn.headers
+        headers["Content-Type"] = "application/json"
+        headers["User-Agent"] = "yookassarb/#{Yookassa::VERSION}"
+      end
+
+      def configure_auth(conn)
+        creds = client.config.credentials
+        auth_token = creds[:auth_token]
+        if auth_token
+          conn.request :authorization, "Bearer", auth_token
+        else
+          conn.request :authorization, :basic, creds[:shop_id].to_s, creds[:api_key].to_s
+        end
+      end
+
+      def configure_middleware(conn)
+        config = client.config
+        conn.use Yookassa::Middleware::Idempotency
+        conn.use Yookassa::Middleware::Retry,
+                 max_retries: config.max_retries,
+                 retry_delay: config.retry_delay
+        conn.use Yookassa::Middleware::ErrorHandler
+        conn.options.timeout = config.timeout
+      end
+
+      def build_collection(path, entity_class:, query: {})
+        data = request(:get, path, query: query)
+        Entities::Collection.new(
+          items: data["items"] || [],
+          next_cursor: data["next_cursor"],
+          entity_class: entity_class
+        )
+      end
+    end
+  end
+end

data/lib/yookassa/resources/deal.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Yookassa
+  module Resources
+    # REST resource for the +/v3/deals+ endpoint.
+    #
+    # Inherits +create+, +find+, and +list+ from {Base}.
+    #
+    # @see https://yookassa.ru/developers/api#create_deal API reference
+    class Deal < Base
+      resource_path "deals"
+      entity_class Entities::Deal
+    end
+  end
+end

data/lib/yookassa/resources/invoice.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Yookassa
+  module Resources
+    # REST resource for the +/v3/invoices+ endpoint.
+    #
+    # @see https://yookassa.ru/developers/api YooKassa API reference
+    class Invoice < Base
+      # Creates a new invoice.
+      #
+      # @param params [Hash] invoice parameters
+      # @param idempotency_key [String, nil] optional idempotency key
+      # @return [Entities::Base]
+      # @raise [ApiError] on API failure
+      def create(params, idempotency_key: nil)
+        data = request(:post, "invoices", body: params, idempotency_key: idempotency_key)
+        Entities::Base.new(data)
+      end
+
+      # Retrieves an invoice by ID.
+      #
+      # @param invoice_id [String] the invoice identifier
+      # @return [Entities::Base]
+      # @raise [NotFoundError] if invoice does not exist
+      def find(invoice_id)
+        data = request(:get, "invoices/#{invoice_id}")
+        Entities::Base.new(data)
+      end
+    end
+  end
+end

data/lib/yookassa/resources/payment.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Yookassa
+  module Resources
+    # REST resource for the +/v3/payments+ endpoint.
+    #
+    # Supports creating, finding, capturing, canceling, and listing payments.
+    #
+    # @see https://yookassa.ru/developers/api#create_payment API reference
+    class Payment < Base
+      # Creates a new payment.
+      #
+      # @param params [Hash] payment parameters (amount, confirmation, description, etc.)
+      # @param idempotency_key [String, nil] optional idempotency key
+      # @return [Entities::Payment]
+      # @raise [ApiError] on API failure
+      def create(params, idempotency_key: nil)
+        data = request(:post, "payments", body: params, idempotency_key: idempotency_key)
+        Entities::Payment.new(data)
+      end
+
+      # Retrieves a payment by ID.
+      #
+      # @param payment_id [String] the payment identifier
+      # @return [Entities::Payment]
+      # @raise [NotFoundError] if payment does not exist
+      def find(payment_id)
+        data = request(:get, "payments/#{payment_id}")
+        Entities::Payment.new(data)
+      end
+
+      # Captures an authorized payment (for two-stage payments).
+      #
+      # @param payment_id [String] the payment identifier
+      # @param params [Hash] optional capture parameters (amount for partial capture, etc.)
+      # @param idempotency_key [String, nil] optional idempotency key
+      # @return [Entities::Payment]
+      # @raise [ApiError] on API failure
+      def capture(payment_id, params = {}, idempotency_key: nil)
+        data = request(:post, "payments/#{payment_id}/capture", body: params, idempotency_key: idempotency_key)
+        Entities::Payment.new(data)
+      end
+
+      # Cancels a payment that has not yet been captured.
+      #
+      # @param payment_id [String] the payment identifier
+      # @param idempotency_key [String, nil] optional idempotency key
+      # @return [Entities::Payment]
+      # @raise [ApiError] on API failure
+      def cancel(payment_id, idempotency_key: nil)
+        data = request(:post, "payments/#{payment_id}/cancel", idempotency_key: idempotency_key)
+        Entities::Payment.new(data)
+      end
+
+      # Lists payments matching the given filters.
+      #
+      # @param filters [Hash] query filters (status, created_at, limit, cursor, etc.)
+      # @return [Entities::Collection<Entities::Payment>]
+      def list(**filters)
+        build_collection("payments", entity_class: Entities::Payment, query: filters)
+      end
+    end
+  end
+end

data/lib/yookassa/resources/payout.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Yookassa
+  module Resources
+    # REST resource for the +/v3/payouts+ endpoint.
+    #
+    # Inherits +create+, +find+, and +list+ from {Base}.
+    #
+    # @see https://yookassa.ru/developers/api#create_payout API reference
+    class Payout < Base
+      resource_path "payouts"
+      entity_class Entities::Payout
+    end
+  end
+end

data/lib/yookassa/resources/receipt.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Yookassa
+  module Resources
+    # REST resource for the +/v3/receipts+ endpoint.
+    #
+    # Inherits +create+, +find+, and +list+ from {Base}.
+    #
+    # @see https://yookassa.ru/developers/api#create_receipt API reference
+    class Receipt < Base
+      resource_path "receipts"
+      entity_class Entities::Receipt
+    end
+  end
+end

data/lib/yookassa/resources/refund.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Yookassa
+  module Resources
+    # REST resource for the +/v3/refunds+ endpoint.
+    #
+    # Inherits +create+, +find+, and +list+ from {Base}.
+    #
+    # @see https://yookassa.ru/developers/api#create_refund API reference
+    class Refund < Base
+      resource_path "refunds"
+      entity_class Entities::Refund
+    end
+  end
+end

data/lib/yookassa/resources/settings.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Yookassa
+  module Resources
+    # REST resource for the +/v3/me+ endpoint (shop settings).
+    #
+    # @see https://yookassa.ru/developers/api#me_object API reference
+    class Settings < Base
+      # Retrieves the current shop settings and account info.
+      #
+      # @return [Entities::Base] shop settings entity
+      # @raise [ApiError] on API failure
+      def retrieve
+        data = request(:get, "me")
+        Entities::Base.new(data)
+      end
+    end
+  end
+end