payu_pl 0.1.0

data/lib/payu_pl/contracts/refund_create_contract.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+
+module PayuPl
+  module Contracts
+    class RefundCreateContract < Dry::Validation::Contract
+      params do
+        required(:order_id).filled(:string)
+        required(:description).filled(:string)
+        optional(:amount).maybe(:string)
+        optional(:ext_refund_id).maybe(:string)
+      end
+
+      rule(:amount) do
+        next if value.nil?
+
+        amount_string = value.to_s
+        key.failure(PayuPl.t(:numeric_string)) unless amount_string.match?(/\A\d+\z/)
+      end
+
+      rule(:ext_refund_id) do
+        next if value.nil?
+
+        key.failure(PayuPl.t(:max_length, max: 1024)) if value.length > 1024
+      end
+
+      rule(:description) do
+        key.failure(PayuPl.t(:max_length, max: 4000)) if value.length > 4000
+      end
+    end
+  end
+end

data/lib/payu_pl/endpoints.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module PayuPl
+  module Endpoints
+    OAUTH_TOKEN = "/pl/standard/user/oauth/authorize"
+
+    ORDERS = "/api/v2_1/orders"
+
+    def self.order(order_id)
+      "#{ORDERS}/#{URI.encode_www_form_component(order_id.to_s)}"
+    end
+
+    def self.order_captures(order_id)
+      "#{order(order_id)}/captures"
+    end
+
+    def self.order_transactions(order_id)
+      "#{order(order_id)}/transactions"
+    end
+
+    def self.order_refunds(order_id)
+      "#{order(order_id)}/refunds"
+    end
+
+    def self.order_refund(order_id, refund_id)
+      "#{order_refunds(order_id)}/#{URI.encode_www_form_component(refund_id.to_s)}"
+    end
+  end
+end

data/lib/payu_pl/errors.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module PayuPl
+  class Error < StandardError; end
+
+  class ValidationError < Error
+    attr_reader :errors, :input
+
+    def initialize(errors:, input: nil, message: "Validation failed")
+      super(message)
+      @errors = errors
+      @input = input
+    end
+  end
+
+  class NetworkError < Error
+    attr_reader :original
+
+    def initialize(message = "Network error", original: nil)
+      super(message)
+      @original = original
+    end
+  end
+
+  class ResponseError < Error
+    attr_reader :http_status, :correlation_id, :raw_body, :parsed_body
+
+    def initialize(message, http_status:, correlation_id: nil, raw_body: nil, parsed_body: nil)
+      super(message)
+      @http_status = http_status
+      @correlation_id = correlation_id
+      @raw_body = raw_body
+      @parsed_body = parsed_body
+    end
+  end
+
+  class ClientError < ResponseError; end
+  class UnauthorizedError < ClientError; end
+  class ForbiddenError < ClientError; end
+  class NotFoundError < ClientError; end
+  class RateLimitedError < ClientError; end
+
+  class ServerError < ResponseError; end
+end

data/lib/payu_pl/operations/base.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "uri"
+require "dry-initializer"
+
+module PayuPl
+  module Operations
+    class Base
+      extend Dry::Initializer
+
+      option :client
+
+      private
+
+      def transport
+        client.transport
+      end
+
+      def escape_path(segment)
+        URI.encode_www_form_component(segment.to_s)
+      end
+
+      def validate_contract!(contract_class, params, input: params)
+        result = contract_class.new.call(params)
+        return if result.success?
+
+        raise ValidationError.new(errors: result.errors.to_h, input: input)
+      end
+
+      def validate_id!(value, input_key: :id)
+        result = Contracts::IdContract.new.call(id: value.to_s)
+        return if result.success?
+
+        raise ValidationError.new(
+          errors: { input_key => result.errors.to_h[:id] }.compact,
+          input: { input_key => value }
+        )
+      end
+
+      def validate_ids!(**ids)
+        id_contract = Contracts::IdContract.new
+        errors = {}
+
+        ids.each do |key, value|
+          res = id_contract.call(id: value.to_s)
+          errors[key] = res.errors.to_h[:id] unless res.success?
+        end
+
+        return if errors.empty?
+
+        raise ValidationError.new(errors: errors, input: ids)
+      end
+    end
+  end
+end

data/lib/payu_pl/orders/cancel.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module PayuPl
+  module Orders
+    class Cancel < Operations::Base
+      def call(order_id)
+        validate_id!(order_id, input_key: :order_id)
+        transport.request(:delete, Endpoints.order(order_id), json: nil)
+      end
+    end
+  end
+end

data/lib/payu_pl/orders/capture.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module PayuPl
+  module Orders
+    class Capture < Operations::Base
+      def call(order_id, amount: nil, currency_code: nil)
+        params = {
+          order_id: order_id.to_s,
+          amount: amount,
+          currency_code: currency_code
+        }
+        validate_contract!(Contracts::CaptureContract, params, input: params)
+
+        path = Endpoints.order_captures(order_id)
+
+        if amount.nil? && currency_code.nil?
+          transport.request(:post, path, json: nil)
+        else
+          payload = {
+            amount: amount,
+            currencyCode: currency_code
+          }.compact
+          transport.request(:post, path, json: payload)
+        end
+      end
+    end
+  end
+end

data/lib/payu_pl/orders/create.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module PayuPl
+  module Orders
+    class Create < Operations::Base
+      def call(order_create_request)
+        validate_contract!(Contracts::OrderCreateContract, order_create_request, input: order_create_request)
+
+        # Do NOT use result.to_h here: dry-schema would drop unknown keys, and PayU supports many optional fields.
+        transport.request(:post, Endpoints::ORDERS, json: order_create_request)
+      end
+    end
+  end
+end

data/lib/payu_pl/orders/retrieve.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module PayuPl
+  module Orders
+    class Retrieve < Operations::Base
+      def call(order_id)
+        validate_id!(order_id, input_key: :order_id)
+        transport.request(:get, Endpoints.order(order_id))
+      end
+    end
+  end
+end

data/lib/payu_pl/orders/transactions.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module PayuPl
+  module Orders
+    class Transactions < Operations::Base
+      def call(order_id)
+        validate_id!(order_id, input_key: :order_id)
+        transport.request(:get, Endpoints.order_transactions(order_id))
+      end
+    end
+  end
+end

data/lib/payu_pl/refunds/create.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module PayuPl
+  module Refunds
+    class Create < Operations::Base
+      def call(order_id, description:, amount: nil, ext_refund_id: nil)
+        params = {
+          order_id: order_id.to_s,
+          description: description,
+          amount: amount,
+          ext_refund_id: ext_refund_id
+        }
+        validate_contract!(Contracts::RefundCreateContract, params, input: params)
+
+        refund = {
+          description: description,
+          amount: amount,
+          extRefundId: ext_refund_id
+        }.compact
+
+        transport.request(
+          :post,
+          Endpoints.order_refunds(order_id),
+          json: { refund: refund }
+        )
+      end
+    end
+  end
+end

data/lib/payu_pl/refunds/list.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module PayuPl
+  module Refunds
+    class List < Operations::Base
+      def call(order_id)
+        validate_id!(order_id, input_key: :order_id)
+        transport.request(:get, Endpoints.order_refunds(order_id))
+      end
+    end
+  end
+end

data/lib/payu_pl/refunds/retrieve.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module PayuPl
+  module Refunds
+    class Retrieve < Operations::Base
+      def call(order_id, refund_id)
+        validate_ids!(order_id: order_id, refund_id: refund_id)
+        transport.request(:get, Endpoints.order_refund(order_id, refund_id))
+      end
+    end
+  end
+end

data/lib/payu_pl/transport.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module PayuPl
+  class Transport
+    def initialize(base_url:, access_token_provider:, open_timeout: 10, read_timeout: 30)
+      @base_url = base_url
+      @access_token_provider = access_token_provider
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+
+      validate!
+    end
+
+    def request(method, path, headers: {}, json: :__no_json_argument_given, form: nil, authorize: true)
+      uri = URI.join(@base_url, path)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = @open_timeout
+      http.read_timeout = @read_timeout
+
+      request_klass = case method.to_s.downcase
+                      when "get" then Net::HTTP::Get
+                      when "post" then Net::HTTP::Post
+                      when "put" then Net::HTTP::Put
+                      when "delete" then Net::HTTP::Delete
+                      else
+                        raise ArgumentError, "Unsupported HTTP method: #{method.inspect}"
+                      end
+
+      req = request_klass.new(uri)
+      req["Accept"] = "application/json"
+
+      if authorize
+        token = @access_token_provider.call
+        raise ArgumentError, "access_token is required for this request (call oauth_token first or pass access_token:)" if token.nil? || token.to_s.empty?
+
+        req["Authorization"] = "Bearer #{token}"
+      end
+
+      headers.each { |k, v| req[k] = v }
+
+      if method.to_s.downcase == "get"
+        # PayU rejects GET with a body (HTTP 403) per RFC 9110 note in docs
+        raise ArgumentError, "GET requests must not include a JSON body" if json != :__no_json_argument_given && !json.nil?
+        raise ArgumentError, "GET requests must not include a form body" if form
+      end
+
+      if form
+        req["Content-Type"] ||= "application/x-www-form-urlencoded"
+        req.body = URI.encode_www_form(form)
+      elsif json != :__no_json_argument_given
+        # json:nil means explicit empty body for endpoints that accept it
+        req["Content-Type"] ||= "application/json"
+        req.body = json.nil? ? nil : JSON.generate(json)
+      end
+
+      begin
+        res = http.request(req)
+      rescue Timeout::Error, Errno::ETIMEDOUT => e
+        raise NetworkError.new("Request timed out", original: e)
+      rescue SocketError, Errno::ECONNREFUSED, Errno::EHOSTUNREACH, EOFError => e
+        raise NetworkError.new("Network failure", original: e)
+      end
+
+      handle_response(res)
+    end
+
+    private
+
+    def validate!
+      uri = URI.parse(@base_url)
+      raise ArgumentError, "base_url must be http(s)" unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+    rescue URI::InvalidURIError
+      raise ArgumentError, "base_url is invalid"
+    end
+
+    def handle_response(res)
+      http_status = res.code.to_i
+      correlation_id = res["Correlation-Id"] || res["correlation-id"]
+      raw_body = res.body
+      parsed = parse_body(res)
+
+      return parsed if http_status >= 200 && http_status < 400
+
+      message = build_error_message(http_status, parsed, raw_body)
+
+      error_class = case http_status
+                    when 401 then UnauthorizedError
+                    when 403 then ForbiddenError
+                    when 404 then NotFoundError
+                    when 429 then RateLimitedError
+                    when 400..499 then ClientError
+                    else
+                      ServerError
+                    end
+
+      raise error_class.new(
+        message,
+        http_status: http_status,
+        correlation_id: correlation_id,
+        raw_body: raw_body,
+        parsed_body: parsed
+      )
+    end
+
+    def parse_body(res)
+      body = res.body
+      return nil if body.nil? || body.empty?
+
+      content_type = res["Content-Type"].to_s
+      if content_type.include?("application/json") || body.match?(/\A\s*[\[{]/)
+        JSON.parse(body)
+      else
+        body
+      end
+    rescue JSON::ParserError
+      body
+    end
+
+    def build_error_message(http_status, parsed, raw_body)
+      status_desc = nil
+      status_code = nil
+
+      if parsed.is_a?(Hash) && parsed["status"].is_a?(Hash)
+        status_code = parsed.dig("status", "statusCode")
+        status_desc = parsed.dig("status", "statusDesc")
+      end
+
+      parts = ["HTTP #{http_status}"]
+      parts << status_code if status_code
+      parts << status_desc if status_desc
+
+      if parts.length == 1
+        preview = raw_body.to_s.strip
+        preview = "#{preview.each_char.take(300).join}…" if preview.length > 300
+        parts << preview unless preview.empty?
+      end
+
+      parts.compact.join(" - ")
+    end
+  end
+end

data/lib/payu_pl/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PayuPl
+  VERSION = "0.1.0"
+end

data/lib/payu_pl.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "payu_pl/version"
+require_relative "payu_pl/configuration"
+require_relative "payu_pl/errors"
+require_relative "payu_pl/endpoints"
+require_relative "payu_pl/transport"
+
+require_relative "payu_pl/operations/base"
+
+require_relative "payu_pl/contracts/order_create_contract"
+require_relative "payu_pl/contracts/id_contract"
+require_relative "payu_pl/contracts/capture_contract"
+require_relative "payu_pl/contracts/refund_create_contract"
+
+require_relative "payu_pl/authorize/oauth_token"
+
+require_relative "payu_pl/orders/create"
+require_relative "payu_pl/orders/retrieve"
+require_relative "payu_pl/orders/capture"
+require_relative "payu_pl/orders/cancel"
+require_relative "payu_pl/orders/transactions"
+
+require_relative "payu_pl/refunds/create"
+require_relative "payu_pl/refunds/list"
+require_relative "payu_pl/refunds/retrieve"
+require_relative "payu_pl/client"
+
+module PayuPl
+end

data/sig/payu_pl.rbs

@@ -0,0 +1,94 @@
+module PayuPl
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  class Configuration
+    attr_accessor locale: Symbol
+    def initialize: () -> void
+  end
+
+  def self.config: () -> Configuration
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.load_translations!: () -> void
+  def self.t: (Symbol | String, **untyped) -> String
+
+  class Error < StandardError
+  end
+
+  class ValidationError < Error
+    attr_reader errors: untyped
+    attr_reader input: untyped
+
+    def initialize: (errors: untyped, ?input: untyped, ?message: String) -> void
+  end
+
+  class NetworkError < Error
+    attr_reader original: untyped
+    def initialize: (?String message, ?original: untyped) -> void
+  end
+
+  class ResponseError < Error
+    attr_reader http_status: Integer
+    attr_reader correlation_id: String?
+    attr_reader raw_body: String?
+    attr_reader parsed_body: untyped
+
+    def initialize: (String message, http_status: Integer, ?correlation_id: String?, ?raw_body: String?, ?parsed_body: untyped) -> void
+  end
+
+  class ClientError < ResponseError
+  end
+
+  class UnauthorizedError < ClientError
+  end
+
+  class ForbiddenError < ClientError
+  end
+
+  class NotFoundError < ClientError
+  end
+
+  class RateLimitedError < ClientError
+  end
+
+  class ServerError < ResponseError
+  end
+
+  class Transport
+    def initialize: (base_url: String, access_token_provider: ^() -> String?, ?open_timeout: Integer, ?read_timeout: Integer) -> void
+    def request: (untyped method, String path, ?headers: Hash[String, String], ?json: untyped, ?form: Hash[untyped, untyped], ?authorize: bool) -> untyped
+  end
+
+  class Client
+    DEFAULT_PRODUCTION_BASE_URL: String
+    DEFAULT_SANDBOX_BASE_URL: String
+
+    attr_reader base_url: String
+    attr_reader client_id: String
+    attr_reader client_secret: String
+    attr_accessor access_token: String?
+
+    def initialize: (
+      client_id: String,
+      client_secret: String,
+      ?access_token: String?,
+      ?base_url: String?,
+      ?environment: Symbol,
+      ?open_timeout: Integer,
+      ?read_timeout: Integer
+    ) -> void
+
+    def oauth_token: (?grant_type: String) -> Hash[String, untyped]
+
+    def create_order: (untyped order_create_request) -> untyped
+    def retrieve_order: (untyped order_id) -> untyped
+    def capture_order: (untyped order_id, ?amount: untyped, ?currency_code: untyped) -> untyped
+    def cancel_order: (untyped order_id) -> untyped
+
+    def create_refund: (untyped order_id, description: String, ?amount: untyped, ?ext_refund_id: untyped) -> untyped
+    def list_refunds: (untyped order_id) -> untyped
+    def retrieve_refund: (untyped order_id, untyped refund_id) -> untyped
+
+    def retrieve_transactions: (untyped order_id) -> untyped
+  end
+end