yookassarb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1af798c77da6146b2481f9d7cff67c0fc98b1f00a07c4b4f2631453bbf752ffe
+  data.tar.gz: a7356f8dc360faa0bc250ac2b4ac3b4f83263b072aca73b64e34a204a09a86cd
+SHA512:
+  metadata.gz: ef838595dd52364e9af5459164d8ba31f3a37f0740bc21cad3817ff577816d73b553c0abfd54c6c727d20a02e18d8bbce93d59beba9577c92877ca1ce615732e
+  data.tar.gz: 8e5368ffe8f4cafeccde9f7eeddd8eac0377aa625ca030ab39bcb23a5f797c1ee19ce4820070d481766a8e84a1b995df7ae18dbb34dcac65ac8733fd60cceabc

data/README.md

@@ -0,0 +1,359 @@
+# YooKassa Ruby SDK
+
+[![Gem Version](https://img.shields.io/gem/v/yookassarb.svg)](https://rubygems.org/gems/yookassarb)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-ruby.svg)](https://www.ruby-lang.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Удобная Ruby-библиотека для работы с [YooKassa API v3](https://yookassa.ru/developers/api). Платежи, возвраты, чеки, выплаты, сделки, вебхуки — всё через простой и идиоматичный Ruby-интерфейс.
+
+## Установка
+
+```ruby
+# Gemfile
+gem "yookassarb"
+```
+
+```bash
+bundle install
+
+# или напрямую
+gem install yookassarb
+```
+
+## Быстрый старт
+
+```ruby
+require "yookassarb"
+
+Yookassa.configure do |config|
+  config.shop_id = "your_shop_id"
+  config.api_key = "your_secret_key"
+end
+
+# Создать платёж
+payment = Yookassa::Payment.create(
+  amount: { value: "100.00", currency: "RUB" },
+  confirmation: { type: "redirect", return_url: "https://example.com/thanks" },
+  description: "Заказ #72"
+)
+
+# Перенаправить пользователя на оплату
+redirect_to payment.confirmation_url
+
+# Проверить статус
+payment = Yookassa::Payment.find(payment.id)
+payment.succeeded?          # => true/false
+payment.waiting_for_capture? # => true/false
+```
+
+## Использование
+
+### Платежи
+
+```ruby
+# Создание
+payment = Yookassa::Payment.create(
+  amount: { value: "500.00", currency: "RUB" },
+  payment_method_data: { type: "bank_card" },
+  confirmation: { type: "redirect", return_url: "https://example.com/return" },
+  description: "Подписка на месяц",
+  metadata: { order_id: "42" }
+)
+
+payment.id                # => "2a7834f6-0001-5000-a000-1da326e5e123"
+payment.status            # => "pending"
+payment.confirmation_url  # => "https://yoomoney.ru/checkout/..."
+payment.amount.value      # => "500.00"
+payment.amount.currency   # => "RUB"
+
+# Подтверждение (capture) двухстадийного платежа
+captured = Yookassa::Payment.capture(payment.id,
+  amount: { value: "500.00", currency: "RUB" }
+)
+
+# Отмена
+canceled = Yookassa::Payment.cancel(payment.id)
+
+# Получение по ID
+payment = Yookassa::Payment.find("2a7834f6-0001-5000-a000-1da326e5e123")
+
+# Список с фильтрами
+payments = Yookassa::Payment.list(
+  created_at_gte: "2024-01-01T00:00:00Z",
+  status: "succeeded",
+  limit: 10
+)
+
+payments.each { |p| puts "#{p.id}: #{p.amount.value} #{p.amount.currency}" }
+payments.has_next? # => true/false — есть ли следующая страница
+```
+
+**Хелперы статусов:**
+
+```ruby
+payment.pending?             # => true
+payment.waiting_for_capture? # => true
+payment.succeeded?           # => true
+payment.canceled?            # => true
+```
+
+### Возвраты
+
+```ruby
+refund = Yookassa::Refund.create(
+  payment_id: "2a7834f6-0001-5000-a000-1da326e5e123",
+  amount: { value: "50.00", currency: "RUB" }
+)
+
+refund = Yookassa::Refund.find(refund.id)
+refunds = Yookassa::Refund.list(payment_id: "2a7834f6-...")
+
+refund.succeeded? # => true
+refund.canceled?  # => true
+```
+
+### Чеки (54-ФЗ)
+
+```ruby
+receipt = Yookassa::Receipt.create(
+  customer: { email: "user@example.com" },
+  items: [
+    {
+      description: "Подписка",
+      amount: { value: "500.00", currency: "RUB" },
+      vat_code: 1,
+      quantity: "1"
+    }
+  ],
+  payment_id: "2a7834f6-...",
+  type: "payment"
+)
+
+receipt = Yookassa::Receipt.find(receipt.id)
+receipts = Yookassa::Receipt.list(payment_id: "2a7834f6-...")
+```
+
+### Выплаты
+
+```ruby
+payout = Yookassa::Payout.create(
+  amount: { value: "1000.00", currency: "RUB" },
+  payout_destination_data: { type: "bank_card", card: { number: "5555555555554444" } },
+  description: "Выплата продавцу"
+)
+
+payout = Yookassa::Payout.find(payout.id)
+payouts = Yookassa::Payout.list(status: "succeeded")
+
+payout.succeeded? # => true
+payout.canceled?  # => true
+```
+
+### Сделки
+
+```ruby
+deal = Yookassa::Deal.create(
+  type: "safe_deal",
+  fee_moment: "payment_succeeded",
+  description: "Безопасная сделка"
+)
+
+deal = Yookassa::Deal.find(deal.id)
+deals = Yookassa::Deal.list(status: "opened")
+
+deal.opened? # => true
+deal.closed? # => true
+```
+
+### Вебхуки (управление подписками)
+
+```ruby
+client = Yookassa::Client.new(shop_id: "id", api_key: "key")
+
+# Подписаться на событие
+webhook = client.webhooks.create(
+  event: "payment.succeeded",
+  url: "https://example.com/webhooks/yookassa"
+)
+
+# Список подписок
+client.webhooks.list.each { |wh| puts "#{wh.id}: #{wh.event}" }
+
+# Удалить подписку
+client.webhooks.delete(webhook.id)
+```
+
+### Счета
+
+```ruby
+client = Yookassa::Client.new(shop_id: "id", api_key: "key")
+
+invoice = client.invoices.create(
+  payment_data: {
+    amount: { value: "1000.00", currency: "RUB" }
+  },
+  cart: [{ description: "Товар", amount: { value: "1000.00", currency: "RUB" }, quantity: 1 }],
+  delivery_method_data: { type: "self" }
+)
+
+invoice = client.invoices.find(invoice.id)
+```
+
+### Настройки магазина
+
+```ruby
+client = Yookassa::Client.new(shop_id: "id", api_key: "key")
+
+settings = client.settings.retrieve
+settings.account_id # => "123456"
+settings.status     # => "enabled"
+```
+
+## Мульти-тенантность
+
+Для работы с несколькими магазинами используйте инстансы `Client`:
+
+```ruby
+shop_a = Yookassa::Client.new(shop_id: "shop_a", api_key: "key_a")
+shop_b = Yookassa::Client.new(shop_id: "shop_b", api_key: "key_b")
+
+payment = shop_a.payments.create(amount: { value: "100.00", currency: "RUB" }, ...)
+payout  = shop_b.payouts.find("payout_id")
+```
+
+Также поддерживается OAuth2-авторизация:
+
+```ruby
+client = Yookassa::Client.new(auth_token: "your_oauth_token")
+```
+
+## Обработка входящих вебхуков
+
+```ruby
+# В контроллере (Rails, Sinatra, etc.)
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def create
+    # Проверить IP отправителя
+    unless Yookassa::Webhook::IpChecker.trusted?(request.remote_ip)
+      head :forbidden
+      return
+    end
+
+    # Распарсить уведомление
+    notification = Yookassa::Webhook::Notification.parse(request.raw_post)
+
+    case notification.event
+    when Yookassa::Webhook::EventTypes::PAYMENT_SUCCEEDED
+      handle_payment(notification.object)
+    when Yookassa::Webhook::EventTypes::PAYMENT_CANCELED
+      handle_cancellation(notification.object)
+    when Yookassa::Webhook::EventTypes::REFUND_SUCCEEDED
+      handle_refund(notification.object)
+    end
+
+    head :ok
+  end
+
+  private
+
+  def handle_payment(payment)
+    order = Order.find_by(payment_id: payment.id)
+    order.complete! if payment.succeeded?
+  end
+end
+```
+
+**Типы событий:**
+
+| Константа | Значение |
+|-----------|----------|
+| `PAYMENT_WAITING_FOR_CAPTURE` | `payment.waiting_for_capture` |
+| `PAYMENT_SUCCEEDED` | `payment.succeeded` |
+| `PAYMENT_CANCELED` | `payment.canceled` |
+| `REFUND_SUCCEEDED` | `refund.succeeded` |
+| `PAYOUT_SUCCEEDED` | `payout.succeeded` |
+| `PAYOUT_CANCELED` | `payout.canceled` |
+| `DEAL_CLOSED` | `deal.closed` |
+
+## Обработка ошибок
+
+```ruby
+begin
+  Yookassa::Payment.create(amount: { value: "-1", currency: "RUB" })
+rescue Yookassa::BadRequestError => e
+  e.http_code    # => 400
+  e.code         # => "invalid_request"
+  e.description  # => "Невалидное значение параметра amount"
+  e.parameter    # => "amount"
+rescue Yookassa::UnauthorizedError
+  # Неверные креденшлы (401)
+rescue Yookassa::ForbiddenError
+  # Нет доступа (403)
+rescue Yookassa::NotFoundError
+  # Объект не найден (404)
+rescue Yookassa::TooManyRequestsError
+  # Превышен лимит запросов (429)
+rescue Yookassa::InternalServerError
+  # Ошибка на стороне YooKassa (500)
+rescue Yookassa::ConnectionError
+  # Проблемы с сетью
+rescue Yookassa::TimeoutError
+  # Таймаут запроса
+end
+```
+
+## Конфигурация
+
+```ruby
+Yookassa.configure do |config|
+  # Аутентификация (один из двух вариантов)
+  config.shop_id    = "your_shop_id"   # ID магазина
+  config.api_key    = "your_secret_key" # Секретный ключ
+  # или
+  config.auth_token = "oauth_token"     # OAuth2-токен
+
+  # Настройки HTTP
+  config.timeout     = 30   # таймаут запроса в секундах (по умолчанию: 30)
+  config.max_retries = 3    # макс. количество повторов (по умолчанию: 3)
+  config.retry_delay = 1.8  # базовая задержка между повторами в секундах (по умолчанию: 1.8)
+  config.logger      = Rails.logger  # логгер (по умолчанию: nil)
+end
+```
+
+## Встроенные механизмы
+
+### Идемпотентность
+
+POST и DELETE запросы автоматически получают заголовок `Idempotence-Key` (UUID v4). Можно передать свой:
+
+```ruby
+Yookassa::Payment.create(params, idempotency_key: "my-unique-key-123")
+```
+
+### Автоматические повторы
+
+SDK автоматически повторяет запросы при HTTP 202 (Accepted), 500 и сетевых ошибках. Задержка растёт линейно: `retry_delay * attempt`.
+
+### Обработка ошибок API
+
+HTTP-ошибки автоматически преобразуются в типизированные исключения с полным контекстом (код, описание, параметр, тело ответа).
+
+## Совместимость
+
+- Ruby >= 3.1
+- Faraday 1.x или 2.x
+
+## Разработка
+
+```bash
+bundle install
+bundle exec rspec          # запуск тестов
+bundle exec rubocop        # линтинг
+gem build yookassarb.gemspec # сборка гема
+```
+
+## Лицензия
+
+[MIT](LICENSE)

data/lib/yookassa/client.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Yookassa
+  # API client that holds configuration and provides access to resource endpoints.
+  #
+  # You can use the global client via {Yookassa.default_client} or create
+  # an isolated instance for multi-shop setups.
+  #
+  # @example Standalone client
+  #   client = Yookassa::Client.new(shop_id: "123", api_key: "key_...")
+  #   payment = client.payments.create(amount: { value: "100.00", currency: "RUB" })
+  class Client
+    # @return [Configuration] the client's configuration
+    attr_reader :config
+
+    # Creates a new API client.
+    #
+    # @param shop_id [String, nil] YooKassa shop identifier
+    # @param api_key [String, nil] secret API key
+    # @param auth_token [String, nil] OAuth token (alternative to shop_id/api_key)
+    # @param options [Hash] additional options (:timeout, :max_retries, :retry_delay, :logger)
+    def initialize(shop_id: nil, api_key: nil, auth_token: nil, **options)
+      @config = Configuration.new
+      @config.shop_id = shop_id
+      @config.api_key = api_key
+      @config.auth_token = auth_token
+      @config.timeout = options[:timeout] if options.key?(:timeout)
+      @config.max_retries = options[:max_retries] if options.key?(:max_retries)
+      @config.retry_delay = options[:retry_delay] if options.key?(:retry_delay)
+      @config.logger = options[:logger] if options.key?(:logger)
+    end
+
+    # @return [Resources::Payment] payment resource endpoint
+    def payments
+      @payments ||= Resources::Payment.new(self)
+    end
+
+    # @return [Resources::Refund] refund resource endpoint
+    def refunds
+      @refunds ||= Resources::Refund.new(self)
+    end
+
+    # @return [Resources::Receipt] receipt resource endpoint
+    def receipts
+      @receipts ||= Resources::Receipt.new(self)
+    end
+
+    # @return [Resources::Payout] payout resource endpoint
+    def payouts
+      @payouts ||= Resources::Payout.new(self)
+    end
+
+    # @return [Resources::Deal] deal resource endpoint
+    def deals
+      @deals ||= Resources::Deal.new(self)
+    end
+
+    # @return [Resources::Webhook] webhook resource endpoint
+    def webhooks
+      @webhooks ||= Resources::Webhook.new(self)
+    end
+
+    # @return [Resources::Invoice] invoice resource endpoint
+    def invoices
+      @invoices ||= Resources::Invoice.new(self)
+    end
+
+    # @return [Resources::Settings] shop settings resource endpoint
+    def settings
+      @settings ||= Resources::Settings.new(self)
+    end
+  end
+end

data/lib/yookassa/configuration.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Yookassa
+  # Holds API credentials and connection settings for the YooKassa API.
+  #
+  # @example Using shop_id + api_key
+  #   Yookassa.configure do |config|
+  #     config.shop_id = "123456"
+  #     config.api_key = "live_..."
+  #   end
+  #
+  # @example Using OAuth token
+  #   Yookassa.configure do |config|
+  #     config.auth_token = "oauth_token_..."
+  #   end
+  class Configuration
+    # @return [String, nil] YooKassa shop (merchant) identifier
+    attr_accessor :shop_id
+
+    # @return [String, nil] secret API key for Basic auth
+    attr_accessor :api_key
+
+    # @return [String, nil] OAuth token (used instead of shop_id/api_key when set)
+    attr_accessor :auth_token
+
+    # @return [Integer] HTTP request timeout in seconds (default: 30)
+    attr_accessor :timeout
+
+    # @return [Integer] maximum number of retries on failure (default: 3)
+    attr_accessor :max_retries
+
+    # @return [Float] base delay between retries in seconds (default: 1.8)
+    attr_accessor :retry_delay
+
+    # @return [Logger, nil] optional logger for request/response debugging
+    attr_accessor :logger
+
+    def initialize
+      @timeout = 30
+      @max_retries = 3
+      @retry_delay = 1.8
+      @logger = nil
+    end
+
+    # Checks whether credentials are present (non-raising).
+    #
+    # @return [Boolean] +true+ if auth_token is set, or both shop_id and api_key are set
+    def validate
+      return true unless auth_token.to_s.empty?
+      return false if shop_id.to_s.empty?
+      return false if api_key.to_s.empty?
+
+      true
+    end
+
+    # Validates that credentials are present, raising on failure.
+    #
+    # @raise [Yookassa::Error] if required credentials are missing
+    # @return [void]
+    def validate!
+      return unless auth_token.to_s.empty?
+      raise Yookassa::Error, "shop_id is required (or provide auth_token)" if shop_id.to_s.empty?
+      raise Yookassa::Error, "api_key is required (or provide auth_token)" if api_key.to_s.empty?
+    end
+
+    # Returns the active credential set for HTTP authentication.
+    #
+    # @return [Hash] either +{ auth_token: ... }+ or +{ shop_id: ..., api_key: ... }+
+    def credentials
+      if auth_token && !auth_token.to_s.empty?
+        { auth_token: auth_token }
+      else
+        { shop_id: shop_id, api_key: api_key }
+      end
+    end
+  end
+end

data/lib/yookassa/entities/base.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Yookassa
+  module Entities
+    # Base entity class that wraps API response hashes with dynamic attribute access.
+    #
+    # Attributes returned by the API are accessible as methods via +method_missing+.
+    # Nested hashes are automatically wrapped into entity instances, and arrays of
+    # hashes become arrays of entities.
+    #
+    # @example
+    #   entity = Yookassa::Entities::Base.new(id: "abc", amount: { value: "100", currency: "RUB" })
+    #   entity.id              # => "abc"
+    #   entity.amount.value    # => "100"
+    #   entity[:id]            # => "abc"
+    #   entity.to_h            # => { "id" => "abc", "amount" => { "value" => "100", "currency" => "RUB" } }
+    class Base
+      # @return [Hash<String, Object>] normalized attribute hash (string keys)
+      attr_reader :attributes
+
+      # @param data [Hash, #to_h] raw API response data
+      def initialize(data)
+        @attributes = self.class.send(:normalize, data)
+      end
+
+      # Hash-style attribute access.
+      #
+      # @param key [String, Symbol] attribute name
+      # @return [Object, nil]
+      def [](key)
+        @attributes[key.to_s]
+      end
+
+      # Returns the raw attribute hash.
+      #
+      # @return [Hash<String, Object>]
+      def to_h
+        @attributes
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        @attributes.key?(method_name.to_s) || super
+      end
+
+      private
+
+      def method_missing(method_name, *args)
+        key = method_name.to_s
+        if @attributes.key?(key)
+          wrap_value(@attributes[key])
+        else
+          super
+        end
+      end
+
+      def wrap_value(value)
+        klass = self.class
+        case value
+        when Hash
+          klass.new(value)
+        when Array
+          value.map { |item| item.is_a?(Hash) ? klass.new(item) : item }
+        else
+          value
+        end
+      end
+
+      def self.normalize(data)
+        case data
+        when Hash
+          data.transform_keys(&:to_s)
+        else
+          begin
+            data.to_h.transform_keys(&:to_s)
+          rescue StandardError
+            {}
+          end
+        end
+      end
+      private_class_method :normalize
+    end
+  end
+end

data/lib/yookassa/entities/collection.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Yookassa
+  module Entities
+    # Paginated collection of entities with cursor-based navigation.
+    #
+    # Includes +Enumerable+ so standard methods (+map+, +select+, +first+, etc.)
+    # work out of the box.
+    #
+    # @example Iterating over payments
+    #   payments = client.payments.list(limit: 10)
+    #   payments.each { |p| puts p.id }
+    #   payments.has_next?   # => true
+    #   payments.next_cursor # => "cursor_abc"
+    class Collection
+      include Enumerable
+
+      # @return [Array<Entities::Base>] wrapped entity objects
+      attr_reader :items
+
+      # @return [String, nil] cursor for fetching the next page
+      attr_reader :next_cursor
+
+      # @param items [Array<Hash>] raw item hashes from API response
+      # @param next_cursor [String, nil] pagination cursor for the next page
+      # @param entity_class [Class] entity class to wrap each item (default: {Entities::Base})
+      def initialize(items:, next_cursor: nil, entity_class: Entities::Base)
+        @items = items.map { |item| entity_class.new(item) }
+        @next_cursor = next_cursor
+      end
+
+      # Yields each entity in the collection.
+      #
+      # @yield [entity] each wrapped entity
+      # @yieldparam entity [Entities::Base]
+      def each(&)
+        @items.each(&)
+      end
+
+      # @return [Integer] number of items in this page
+      def size
+        @items.size
+      end
+      alias length size
+
+      # @return [Boolean] +true+ if the collection has no items
+      def empty?
+        @items.empty?
+      end
+
+      # @return [Boolean] +true+ if more pages are available
+      def has_next?
+        !@next_cursor.to_s.empty?
+      end
+    end
+  end
+end

data/lib/yookassa/entities/deal.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Yookassa
+  module Entities
+    # Deal (Safe Deal) entity with status helpers.
+    #
+    # @see https://yookassa.ru/developers/api#deal_object Deal object reference
+    class Deal < Base
+      # @return [Boolean] +true+ if the deal is currently open
+      def opened?
+        status == "opened"
+      end
+
+      # @return [Boolean] +true+ if the deal has been closed
+      def closed?
+        status == "closed"
+      end
+    end
+  end
+end