yookassarb 0.1.0

data/lib/yookassa/resources/webhook.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Yookassa
+  module Resources
+    # REST resource for the +/v3/webhooks+ endpoint.
+    #
+    # Unlike other resources, webhooks support +create+, +list+, and +delete+
+    # but not +find+ (individual lookup is not available in the API).
+    #
+    # @see https://yookassa.ru/developers/api#create_webhook API reference
+    class Webhook < Base
+      # Registers a new webhook subscription.
+      #
+      # @param params [Hash] webhook parameters (event, url)
+      # @param idempotency_key [String, nil] optional idempotency key
+      # @return [Entities::WebhookObj]
+      # @raise [ApiError] on API failure
+      def create(params, idempotency_key: nil)
+        data = request(:post, "webhooks", body: params, idempotency_key: idempotency_key)
+        Entities::WebhookObj.new(data)
+      end
+
+      # Lists all registered webhook subscriptions.
+      #
+      # @return [Entities::Collection<Entities::WebhookObj>]
+      def list
+        data = request(:get, "webhooks")
+        Entities::Collection.new(
+          items: data["items"] || [],
+          entity_class: Entities::WebhookObj
+        )
+      end
+
+      # Deletes a webhook subscription.
+      #
+      # @param webhook_id [String] the webhook identifier
+      # @return [true] always returns +true+ on success
+      # @raise [NotFoundError] if webhook does not exist
+      def delete(webhook_id)
+        request(:delete, "webhooks/#{webhook_id}")
+        true
+      end
+    end
+  end
+end

data/lib/yookassa/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Ruby SDK for the YooKassa payment gateway API.
+module Yookassa
+  # Current gem version.
+  VERSION = "0.1.0" unless const_defined?(:VERSION)
+end

data/lib/yookassa/webhook/event_types.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Yookassa
+  module Webhook
+    # Constants for YooKassa webhook event types.
+    #
+    # @example Subscribing to a specific event
+    #   client.webhooks.create(
+    #     event: Yookassa::Webhook::EventTypes::PAYMENT_SUCCEEDED,
+    #     url: "https://example.com/webhooks"
+    #   )
+    #
+    # @example Checking event type
+    #   EventTypes::ALL.include?(notification.event) # => true
+    module EventTypes
+      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"
+
+      # All known event types.
+      ALL = [
+        PAYMENT_WAITING_FOR_CAPTURE,
+        PAYMENT_SUCCEEDED,
+        PAYMENT_CANCELED,
+        REFUND_SUCCEEDED,
+        PAYOUT_SUCCEEDED,
+        PAYOUT_CANCELED,
+        DEAL_CLOSED
+      ].freeze
+    end
+  end
+end

data/lib/yookassa/webhook/ip_checker.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module Yookassa
+  module Webhook
+    # Validates webhook request source IPs against YooKassa's trusted networks.
+    #
+    # Use this in your webhook endpoint to verify that requests actually come
+    # from YooKassa and not from a third party.
+    #
+    # @example Rails before_action
+    #   before_action :verify_yookassa_ip, only: :webhook
+    #
+    #   def verify_yookassa_ip
+    #     head :forbidden unless Yookassa::Webhook::IpChecker.trusted?(request.remote_ip)
+    #   end
+    #
+    # @see https://yookassa.ru/developers/using-api/webhooks IP addresses
+    module IpChecker
+      # YooKassa's trusted IP networks (IPv4 and IPv6).
+      TRUSTED_NETWORKS = [
+        IPAddr.new("185.71.76.0/27"),
+        IPAddr.new("185.71.77.0/27"),
+        IPAddr.new("77.75.153.0/25"),
+        IPAddr.new("77.75.156.11"),
+        IPAddr.new("77.75.156.35"),
+        IPAddr.new("77.75.154.128/25"),
+        IPAddr.new("2a02:5180::/32")
+      ].freeze
+
+      # Checks whether the given IP belongs to a YooKassa trusted network.
+      #
+      # @param ip [String] the IP address to check
+      # @return [Boolean] +true+ if the IP is trusted
+      def self.trusted?(ip)
+        addr = IPAddr.new(ip.to_s)
+        TRUSTED_NETWORKS.any? { |network| network.include?(addr) }
+      rescue IPAddr::InvalidAddressError
+        false
+      end
+    end
+  end
+end

data/lib/yookassa/webhook/notification.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Yookassa
+  module Webhook
+    # Parses incoming webhook notification payloads from YooKassa.
+    #
+    # Automatically wraps the notification object into the appropriate entity class
+    # (Payment, Refund, Payout, or Deal) based on the event type.
+    #
+    # @example Parsing a webhook in a Rails controller
+    #   notification = Yookassa::Webhook::Notification.parse(request.body.read)
+    #   notification.event     # => "payment.succeeded"
+    #   notification.object    # => #<Yookassa::Entities::Payment ...>
+    #   notification.object.id # => "2a5b8f3c-..."
+    class Notification
+      # @return [String] the event type (e.g. "payment.succeeded")
+      attr_reader :event
+
+      # @return [String] the notification type (always "notification")
+      attr_reader :type
+
+      # @return [Entities::Base] the wrapped entity (Payment, Refund, Payout, or Deal)
+      attr_reader :object
+
+      # Maps event type prefixes to entity classes.
+      ENTITY_MAP = {
+        "payment" => Entities::Payment,
+        "refund" => Entities::Refund,
+        "payout" => Entities::Payout,
+        "deal" => Entities::Deal
+      }.freeze
+
+      # @param event [String] the event type
+      # @param type [String] the notification type
+      # @param object [Entities::Base] the wrapped entity
+      def initialize(event:, type:, object:)
+        @event = event
+        @type = type
+        @object = object
+      end
+
+      # Parses a raw webhook payload (JSON string or Hash) into a {Notification}.
+      #
+      # @param json_or_hash [String, Hash] the raw webhook body
+      # @return [Notification]
+      # @raise [JSON::ParserError] if string input is not valid JSON
+      def self.parse(json_or_hash)
+        data = json_or_hash.is_a?(String) ? JSON.parse(json_or_hash) : json_or_hash
+        event = data["event"]
+        entity_type = event.to_s.split(".").first
+        entity_class = ENTITY_MAP[entity_type] || Entities::Base
+
+        new(
+          event: event,
+          type: data["type"],
+          object: entity_class.new(data["object"] || {})
+        )
+      end
+    end
+  end
+end

data/lib/yookassarb.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+require_relative "yookassa/version"
+require_relative "yookassa/errors"
+require_relative "yookassa/configuration"
+require_relative "yookassa/client"
+
+require_relative "yookassa/middleware/idempotency"
+require_relative "yookassa/middleware/retry"
+require_relative "yookassa/middleware/error_handler"
+
+require_relative "yookassa/entities/base"
+require_relative "yookassa/entities/payment"
+require_relative "yookassa/entities/refund"
+require_relative "yookassa/entities/receipt"
+require_relative "yookassa/entities/payout"
+require_relative "yookassa/entities/deal"
+require_relative "yookassa/entities/webhook_obj"
+require_relative "yookassa/entities/collection"
+
+require_relative "yookassa/resources/base"
+require_relative "yookassa/resources/payment"
+require_relative "yookassa/resources/refund"
+require_relative "yookassa/resources/receipt"
+require_relative "yookassa/resources/payout"
+require_relative "yookassa/resources/deal"
+require_relative "yookassa/resources/webhook"
+require_relative "yookassa/resources/invoice"
+require_relative "yookassa/resources/settings"
+
+require_relative "yookassa/webhook/event_types"
+require_relative "yookassa/webhook/notification"
+require_relative "yookassa/webhook/ip_checker"
+
+# Ruby SDK for the YooKassa payment gateway API (v3).
+#
+# Provides a clean, idiomatic interface for payments, refunds, receipts,
+# payouts, deals, webhooks, and shop settings.
+#
+# @example Quick start
+#   Yookassa.configure do |config|
+#     config.shop_id = "123456"
+#     config.api_key = "live_..."
+#   end
+#
+#   payment = Yookassa::Payment.create(
+#     amount: { value: "100.00", currency: "RUB" },
+#     confirmation: { type: "redirect", return_url: "https://example.com" },
+#     description: "Order #42"
+#   )
+#   redirect_to payment.confirmation_url
+#
+# @see https://yookassa.ru/developers/api YooKassa API documentation
+module Yookassa
+  class << self
+    # Yields the global {Configuration} instance for setting credentials.
+    #
+    # @yield [config] the configuration object
+    # @yieldparam config [Configuration]
+    # @return [Configuration]
+    #
+    # @example
+    #   Yookassa.configure do |config|
+    #     config.shop_id = "123456"
+    #     config.api_key = "live_..."
+    #   end
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    # Returns the global {Configuration} instance, creating one if needed.
+    #
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Resets global configuration and the default client to initial state.
+    #
+    # @return [void]
+    def reset_configuration!
+      @configuration = Configuration.new
+      @default_client = nil
+    end
+
+    # Returns the shared {Client} built from the global configuration.
+    # Lazily initialized on first call.
+    #
+    # @return [Client]
+    def default_client
+      @default_client ||= Client.new(
+        shop_id: configuration.shop_id,
+        api_key: configuration.api_key,
+        auth_token: configuration.auth_token,
+        timeout: configuration.timeout,
+        max_retries: configuration.max_retries,
+        retry_delay: configuration.retry_delay,
+        logger: configuration.logger
+      )
+    end
+  end
+
+  # Convenience wrapper for payment operations via the default client.
+  #
+  # @example Create a payment
+  #   payment = Yookassa::Payment.create(
+  #     amount: { value: "500.00", currency: "RUB" },
+  #     confirmation: { type: "redirect", return_url: "https://example.com" }
+  #   )
+  #
+  # @see Resources::Payment
+  class Payment
+    class << self
+      # Creates a new payment.
+      #
+      # @param params [Hash] payment parameters (amount, confirmation, etc.)
+      # @param idempotency_key [String, nil] optional idempotency key
+      # @return [Entities::Payment]
+      # @raise [ApiError] on API failure
+      def create(params, idempotency_key: nil)
+        Yookassa.default_client.payments.create(params, idempotency_key: idempotency_key)
+      end
+
+      # Retrieves a payment by ID.
+      #
+      # @param payment_id [String] the payment ID
+      # @return [Entities::Payment]
+      # @raise [NotFoundError] if payment does not exist
+      def find(payment_id)
+        Yookassa.default_client.payments.find(payment_id)
+      end
+
+      # Captures an authorized payment.
+      #
+      # @param payment_id [String] the payment ID
+      # @param params [Hash] optional capture parameters (amount, 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)
+        Yookassa.default_client.payments.capture(payment_id, params, idempotency_key: idempotency_key)
+      end
+
+      # Cancels a payment.
+      #
+      # @param payment_id [String] the payment ID
+      # @param idempotency_key [String, nil] optional idempotency key
+      # @return [Entities::Payment]
+      # @raise [ApiError] on API failure
+      def cancel(payment_id, idempotency_key: nil)
+        Yookassa.default_client.payments.cancel(payment_id, idempotency_key: idempotency_key)
+      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)
+        Yookassa.default_client.payments.list(**filters)
+      end
+    end
+  end
+
+  # Base class for convenience shortcuts that delegate CRUD to the default client.
+  #
+  # Subclasses call {.delegates_to} to specify which resource method on {Client}
+  # to use for delegation.
+  #
+  # @abstract Subclass and call +delegates_to :resource_method+
+  class ResourceShortcut
+    class << self
+      # Declares which {Client} method this shortcut delegates to.
+      #
+      # @param method [Symbol] the client resource method name
+      # @return [void]
+      def delegates_to(method)
+        @resource_method = method
+      end
+
+      # Creates a new resource.
+      #
+      # @param params [Hash] resource parameters
+      # @param idempotency_key [String, nil] optional idempotency key
+      # @return [Entities::Base]
+      # @raise [ApiError] on API failure
+      def create(params, idempotency_key: nil)
+        resource.create(params, idempotency_key: idempotency_key)
+      end
+
+      # Retrieves a resource by ID.
+      #
+      # @param resource_id [String] the resource ID
+      # @return [Entities::Base]
+      # @raise [NotFoundError] if resource does not exist
+      def find(resource_id)
+        resource.find(resource_id)
+      end
+
+      # Lists resources matching the given filters.
+      #
+      # @param filters [Hash] query filters
+      # @return [Entities::Collection]
+      def list(**filters)
+        resource.list(**filters)
+      end
+
+      private
+
+      def resource
+        Yookassa.default_client.public_send(@resource_method)
+      end
+    end
+  end
+
+  # Convenience wrapper for refund operations via the default client.
+  #
+  # @see Resources::Refund
+  class Refund < ResourceShortcut
+    delegates_to :refunds
+  end
+
+  # Convenience wrapper for receipt operations via the default client.
+  #
+  # @see Resources::Receipt
+  class Receipt < ResourceShortcut
+    delegates_to :receipts
+  end
+
+  # Convenience wrapper for payout operations via the default client.
+  #
+  # @see Resources::Payout
+  class Payout < ResourceShortcut
+    delegates_to :payouts
+  end
+
+  # Convenience wrapper for deal operations via the default client.
+  #
+  # @see Resources::Deal
+  class Deal < ResourceShortcut
+    delegates_to :deals
+  end
+
+  # Namespace for webhook notification handling and IP validation.
+  #
+  # @see Webhook::Notification
+  # @see Webhook::IpChecker
+  module Webhook
+    # Webhook::Notification and Webhook::IpChecker are loaded via require_relative above
+  end
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: yookassarb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Wolfram
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Convenient Ruby wrapper around YooKassa API v3. Supports payments, refunds,
+  receipts, payouts, deals, webhooks, and more.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/yookassa/client.rb
+- lib/yookassa/configuration.rb
+- lib/yookassa/entities/base.rb
+- lib/yookassa/entities/collection.rb
+- lib/yookassa/entities/deal.rb
+- lib/yookassa/entities/payment.rb
+- lib/yookassa/entities/payout.rb
+- lib/yookassa/entities/receipt.rb
+- lib/yookassa/entities/refund.rb
+- lib/yookassa/entities/webhook_obj.rb
+- lib/yookassa/errors.rb
+- lib/yookassa/middleware/error_handler.rb
+- lib/yookassa/middleware/idempotency.rb
+- lib/yookassa/middleware/retry.rb
+- lib/yookassa/resources/base.rb
+- lib/yookassa/resources/deal.rb
+- lib/yookassa/resources/invoice.rb
+- lib/yookassa/resources/payment.rb
+- lib/yookassa/resources/payout.rb
+- lib/yookassa/resources/receipt.rb
+- lib/yookassa/resources/refund.rb
+- lib/yookassa/resources/settings.rb
+- lib/yookassa/resources/webhook.rb
+- lib/yookassa/version.rb
+- lib/yookassa/webhook/event_types.rb
+- lib/yookassa/webhook/ip_checker.rb
+- lib/yookassa/webhook/notification.rb
+- lib/yookassarb.rb
+homepage: https://github.com/Wolframko/yookassarb
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Ruby SDK for YooKassa payment API
+test_files: []