nodexpay 0.1.0

data/lib/nodex_pay/client.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module NodexPay
+  class Client
+    BASE_URLS = {
+      production: "https://app.nodexpay.com/api/v1",
+      testnet: "https://testnet.app.nodexpay.com/api/v1"
+    }.freeze
+
+    DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_READ_TIMEOUT = 30
+    DEFAULT_WRITE_TIMEOUT = 30
+
+    attr_reader :environment, :open_timeout, :read_timeout, :write_timeout
+
+    def initialize(
+      identification_token:,
+      hash_token:,
+      environment:,
+      open_timeout: DEFAULT_OPEN_TIMEOUT,
+      read_timeout: DEFAULT_READ_TIMEOUT,
+      write_timeout: DEFAULT_WRITE_TIMEOUT,
+      transport: nil
+    )
+      unless BASE_URLS.key?(environment)
+        raise ConfigurationError, "environment must be :production or :testnet"
+      end
+
+      @identification_token = Validator.credential(identification_token, "identification_token")
+      @hash_token = Validator.credential(hash_token, "hash_token")
+      @environment = environment
+      @open_timeout = Validator.timeout(open_timeout, "open_timeout")
+      @read_timeout = Validator.timeout(read_timeout, "read_timeout")
+      @write_timeout = Validator.timeout(write_timeout, "write_timeout")
+      @transport = transport || Transport::NetHTTP.new
+
+      unless @transport.respond_to?(:call)
+        raise ConfigurationError, "transport must respond to #call"
+      end
+
+      freeze
+    end
+
+    def create_payment(
+      order_code:,
+      amount: nil,
+      amount_type: nil,
+      color_theme: nil,
+      ui_mode: nil,
+      ext_description: nil,
+      deadline: nil,
+      description: nil
+    )
+      order_code = Validator.order_code(order_code)
+      amount = AmountSerializer.serialize(amount) unless amount.nil?
+
+      fields = authenticated_fields(order_code:, amount:)
+      fields["amount"] = amount unless amount.nil?
+      add_optional_field(fields, "amount_type", Validator.amount_type(amount_type))
+      add_optional_field(fields, "color_theme", Validator.color_theme(color_theme))
+      add_optional_field(fields, "uimode", Validator.ui_mode(ui_mode))
+      add_optional_field(fields, "ext_description", Validator.text(ext_description, "ext_description"))
+      add_optional_field(fields, "deadline", Validator.deadline(deadline))
+      add_optional_field(fields, "description", Validator.text(description, "description"))
+
+      response = perform(:create_payment, "/payment/receive", fields)
+      decode_payment(response.body)
+    end
+
+    def cancel_payment(order_code:)
+      order_code = Validator.order_code(order_code)
+      fields = authenticated_fields(order_code:, amount: nil)
+
+      perform(:cancel_payment, "/payment/cancel", fields)
+      true
+    end
+
+    def verify_payment_result(raw_body)
+      unless raw_body.is_a?(String)
+        raise InvalidResponseError, "Payment Result body must be a String"
+      end
+
+      payload = parse_json_object(raw_body, context: "Payment Result")
+      order_code = Validator.webhook_string(payload, "order_code")
+      transaction_code = Validator.transaction_code(payload)
+      amount = Validator.webhook_string(payload, "amount")
+      symbol = Validator.webhook_string(payload, "symbol")
+      result = Validator.webhook_result(payload)
+      verify_token = Validator.verify_token(payload)
+      chain_id = Validator.webhook_string(payload, "chain_id")
+      transaction_hash = Validator.webhook_string(payload, "transaction_hash")
+
+      unless Signer.valid?(order_code:, amount:, hash_token: @hash_token, signature: verify_token)
+        raise SignatureVerificationError, "Payment Result signature verification failed"
+      end
+
+      PaymentResult.new(
+        order_code:,
+        transaction_code:,
+        amount:,
+        symbol:,
+        result:,
+        chain_id:,
+        transaction_hash:
+      )
+    end
+
+    def inspect
+      "#<#{self.class} environment=#{environment.inspect}>"
+    end
+
+    private
+
+    def authenticated_fields(order_code:, amount:)
+      {
+        "identification_token" => @identification_token,
+        "order_code" => order_code,
+        "verify_token" => Signer.generate(order_code:, amount:, hash_token: @hash_token)
+      }
+    end
+
+    def add_optional_field(fields, name, value)
+      fields[name] = value unless value.nil?
+    end
+
+    def perform(operation, path, fields)
+      request = Transport::Request.new(
+        method: :post,
+        uri: URI("#{BASE_URLS.fetch(environment)}#{path}"),
+        headers: request_headers,
+        body: URI.encode_www_form(fields),
+        open_timeout:,
+        read_timeout:,
+        write_timeout:
+      )
+
+      response = @transport.call(request)
+      validate_transport_response!(response)
+
+      case response.status
+      when 200
+        response
+      when 400
+        raise_api_error(BadRequestError, operation, response)
+      when 503
+        raise_api_error(ServiceUnavailableError, operation, response)
+      else
+        raise_api_error(UnexpectedHTTPStatusError, operation, response)
+      end
+    end
+
+    def request_headers
+      {
+        "Accept" => "application/json",
+        "Content-Type" => "application/x-www-form-urlencoded",
+        "User-Agent" => "nodexpay/#{VERSION} ruby/#{RUBY_VERSION}"
+      }.freeze
+    end
+
+    def validate_transport_response!(response)
+      valid = response.is_a?(Transport::Response)
+      valid &&= response.status.is_a?(Integer)
+      valid &&= response.headers.is_a?(Hash)
+      valid &&= response.headers.all? do |key, value|
+        key.is_a?(String) && key == key.downcase && value.is_a?(String)
+      end
+      valid &&= response.body.is_a?(String)
+      return if valid
+
+      raise InvalidResponseError, "transport returned an invalid response"
+    end
+
+    def raise_api_error(error_class, operation, response)
+      raise error_class.new(
+        operation:,
+        status: response.status,
+        error_codes: extract_error_codes(response.body),
+        response_headers: response.headers,
+        response_body: response.body
+      )
+    end
+
+    def extract_error_codes(body)
+      payload = JSON.parse(body)
+      return [] unless payload.is_a?(Hash)
+
+      values = if payload.key?("errors")
+                 payload["errors"]
+               elsif payload["data"].is_a?(Hash)
+                 payload["data"]["errors"]
+               end
+
+      Array(values).filter_map do |value|
+        case value
+        when Integer then value
+        when String then Integer(value, 10) if /\A[0-9]+\z/.match?(value)
+        end
+      end
+    rescue JSON::ParserError
+      []
+    end
+
+    def decode_payment(body)
+      payload = parse_json_object(body, context: "Payment Request response")
+      url = required_response_string(payload, "url")
+      token = required_response_string(payload, "token")
+      ext_reserved = optional_response_string(payload, "ext_reserved")
+      ext_description = optional_response_string(payload, "ext_description")
+
+      Payment.new(url:, token:, ext_reserved:, ext_description:)
+    end
+
+    def parse_json_object(body, context:)
+      payload = JSON.parse(body)
+      return payload if payload.is_a?(Hash)
+
+      raise InvalidResponseError, "#{context} must be a JSON object"
+    rescue JSON::ParserError
+      raise InvalidResponseError, "#{context} is not valid JSON"
+    end
+
+    def required_response_string(payload, field)
+      value = payload[field]
+      return value.dup.freeze if value.is_a?(String) && !value.empty?
+
+      raise InvalidResponseError, "Payment Request response field #{field.inspect} must be a non-empty String"
+    end
+
+    def optional_response_string(payload, field)
+      value = payload[field]
+      return nil if value.nil?
+      return value.dup.freeze if value.is_a?(String)
+
+      raise InvalidResponseError, "Payment Request response field #{field.inspect} must be a String or null"
+    end
+  end
+end

data/lib/nodex_pay/errors.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module NodexPay
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+  class ValidationError < Error; end
+  class SignatureVerificationError < Error; end
+  class TransportError < Error; end
+  class TimeoutError < TransportError; end
+  class InvalidResponseError < Error; end
+
+  class APIError < Error
+    ERROR_NAMES = {
+      2010 => "RECEIVED_IDENTIFICATION_TOKEN_EMPTY",
+      2011 => "RECEIVED_IDENTIFICATION_TOKEN_INVALID",
+      2020 => "RECEIVED_ORDER_CODE_EMPTY",
+      2021 => "RECEIVED_ORDER_CODE_DUPLICATE",
+      2022 => "RECEIVED_ORDER_CODE_ALREADY_CANCELLED",
+      2023 => "PAYMENT_NOT_FOUND",
+      2024 => "PAYMENT_NOT_CANCELABLE",
+      2030 => "RECEIVED_AMOUNT_INVALID_FORMAT",
+      2040 => "RECEIVED_INVALID_CALLBACK_URL",
+      2050 => "RECEIVED_COLOR_THEME_INVALID_FORMAT",
+      2060 => "RECEIVED_VERIFY_TOKEN_EMPTY",
+      2061 => "RECEIVED_VERIFY_TOKEN_INVALID",
+      2101 => "RECEIVED_EXT_RESERVED_INVALID",
+      2102 => "RECEIVED_EXT_DESCRIPTION_INVALID",
+      2370 => "RECEIVE_CONTRACT_UNPUBLISHED",
+      2460 => "RECEIVED_INVALID_DEADLINE"
+    }.freeze
+
+    attr_reader :operation, :status, :error_codes, :response_headers, :response_body
+
+    def initialize(operation:, status:, error_codes:, response_headers:, response_body:)
+      @operation = operation
+      @status = status
+      @error_codes = error_codes.map { Integer(_1) }.freeze
+      @response_headers = response_headers.to_h.transform_keys(&:to_s).transform_values(&:to_s).freeze
+      @response_body = response_body.to_s.dup.freeze
+
+      details = @error_codes.map { |code| ERROR_NAMES.fetch(code, code.to_s) }
+      suffix = details.empty? ? "" : " (#{details.join(", ")})"
+      super("Nodex Pay #{operation} failed with HTTP #{status}#{suffix}")
+    end
+
+    def inspect
+      "#<#{self.class} operation=#{operation.inspect} status=#{status.inspect} error_codes=#{error_codes.inspect}>"
+    end
+  end
+
+  class BadRequestError < APIError; end
+  class ServiceUnavailableError < APIError; end
+  class UnexpectedHTTPStatusError < APIError; end
+end
+

data/lib/nodex_pay/models.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module NodexPay
+  Payment = Data.define(:url, :token, :ext_reserved, :ext_description) do
+    def initialize(url:, token:, ext_reserved:, ext_description:)
+      super(
+        url: url.dup.freeze,
+        token: token.dup.freeze,
+        ext_reserved: ext_reserved&.dup&.freeze,
+        ext_description: ext_description&.dup&.freeze
+      )
+    end
+  end
+
+  PaymentResult = Data.define(
+    :order_code,
+    :transaction_code,
+    :amount,
+    :symbol,
+    :result,
+    :chain_id,
+    :transaction_hash
+  ) do
+    def initialize(order_code:, transaction_code:, amount:, symbol:, result:, chain_id:, transaction_hash:)
+      super(
+        order_code: order_code.dup.freeze,
+        transaction_code: transaction_code.dup.freeze,
+        amount: amount.dup.freeze,
+        symbol: symbol.dup.freeze,
+        result:,
+        chain_id: chain_id.dup.freeze,
+        transaction_hash: transaction_hash.dup.freeze
+      )
+    end
+
+    def success?
+      result
+    end
+  end
+end

data/lib/nodex_pay/signer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "digest"
+require "openssl"
+
+module NodexPay
+  module Signer
+    module_function
+
+    def generate(order_code:, amount:, hash_token:)
+      Digest::SHA256.hexdigest([order_code, amount, hash_token].join("::"))
+    end
+
+    def valid?(order_code:, amount:, hash_token:, signature:)
+      expected = generate(order_code:, amount:, hash_token:)
+      return false unless signature.bytesize == expected.bytesize
+
+      OpenSSL.fixed_length_secure_compare(expected, signature)
+    end
+  end
+end
+

data/lib/nodex_pay/transport.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+module NodexPay
+  module Transport
+    Request = Data.define(
+      :method,
+      :uri,
+      :headers,
+      :body,
+      :open_timeout,
+      :read_timeout,
+      :write_timeout
+    ) do
+      def initialize(method:, uri:, headers:, body:, open_timeout:, read_timeout:, write_timeout:)
+        super(
+          method:,
+          uri: uri.dup.freeze,
+          headers: immutable_headers(headers),
+          body: body.dup.freeze,
+          open_timeout:,
+          read_timeout:,
+          write_timeout:
+        )
+      end
+
+      private
+
+      def immutable_headers(headers)
+        headers.to_h.each_with_object({}) do |(key, value), copy|
+          copy[key.dup.freeze] = value.dup.freeze
+        end.freeze
+      end
+    end
+
+    Response = Data.define(:status, :headers, :body) do
+      def initialize(status:, headers:, body:)
+        immutable_headers = headers.to_h.each_with_object({}) do |(key, value), copy|
+          copy[key.dup.freeze] = value.dup.freeze
+        end.freeze
+
+        super(status:, headers: immutable_headers, body: body.dup.freeze)
+      end
+    end
+
+    class NetHTTP
+      def call(request)
+        http = Net::HTTP.new(request.uri.host, request.uri.port)
+        http.use_ssl = request.uri.scheme == "https"
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER if http.use_ssl?
+        http.open_timeout = request.open_timeout
+        http.read_timeout = request.read_timeout
+        http.write_timeout = request.write_timeout
+        http.max_retries = 0
+
+        net_request = build_request(request)
+        net_response = http.request(net_request)
+
+        Response.new(
+          status: net_response.code.to_i,
+          headers: response_headers(net_response),
+          body: net_response.body.to_s
+        )
+      rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout => error
+        raise TimeoutError.new("Nodex Pay request timed out for #{safe_target(request.uri)}"), cause: error
+      rescue SocketError, SystemCallError, IOError, EOFError, OpenSSL::SSL::SSLError => error
+        raise TransportError.new("Nodex Pay request failed for #{safe_target(request.uri)}"), cause: error
+      end
+
+      private
+
+      def build_request(request)
+        unless request.method == :post
+          raise ConfigurationError, "NetHTTP transport only supports POST"
+        end
+
+        Net::HTTP::Post.new(request.uri.request_uri, request.headers).tap do |net_request|
+          net_request.body = request.body
+        end
+      end
+
+      def response_headers(response)
+        response.each_header.to_h.transform_keys(&:downcase).transform_values(&:to_s).freeze
+      end
+
+      def safe_target(uri)
+        "#{uri.scheme}://#{uri.host}:#{uri.port}#{uri.path}"
+      end
+    end
+  end
+end

data/lib/nodex_pay/validator.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module NodexPay
+  module Validator
+    AMOUNT_TYPES = %w[USD JPY EUR AED SGD HKD CAD IDR PHP INR KRW].freeze
+    COLOR_THEMES = %w[dark light].freeze
+    UI_MODES = %w[switchable].freeze
+    TRANSACTION_CODE_PATTERN = /\A[A-Za-z0-9]{4}(?:-[A-Za-z0-9]{4}){2}\z/
+    VERIFY_TOKEN_PATTERN = /\A[0-9a-f]{64}\z/
+
+    module_function
+
+    def credential(value, name)
+      return value.dup.freeze if value.is_a?(String) && !value.empty?
+
+      raise ConfigurationError, "#{name} must be a non-empty String"
+    end
+
+    def timeout(value, name)
+      valid = value.is_a?(Numeric) && value.positive?
+      valid &&= !value.respond_to?(:finite?) || value.finite?
+      return value if valid
+
+      raise ConfigurationError, "#{name} must be a positive finite number"
+    end
+
+    def order_code(value)
+      unless value.is_a?(String) && !value.empty? && value.ascii_only? && value.bytesize <= 255
+        raise ValidationError, "order_code must be 1..255 ASCII bytes"
+      end
+
+      value.dup.freeze
+    end
+
+    def amount_type(value)
+      enum(value, "amount_type", AMOUNT_TYPES, :upcase)
+    end
+
+    def color_theme(value)
+      enum(value, "color_theme", COLOR_THEMES, :downcase)
+    end
+
+    def ui_mode(value)
+      enum(value, "ui_mode", UI_MODES, :downcase)
+    end
+
+    def text(value, name)
+      return nil if value.nil?
+      unless value.is_a?(String) && value.encoding == Encoding::UTF_8 && value.valid_encoding? && value.length <= 100
+        raise ValidationError, "#{name} must be a valid UTF-8 String of at most 100 characters"
+      end
+
+      value.dup.freeze
+    end
+
+    def deadline(value)
+      return nil if value.nil?
+
+      seconds = value.is_a?(Time) ? value.to_i : value
+      return seconds if seconds.is_a?(Integer) && !seconds.negative?
+
+      raise ValidationError, "deadline must be a Time or non-negative Integer"
+    end
+
+    def webhook_string(payload, field)
+      value = payload[field]
+      return value.dup.freeze if value.is_a?(String) && !value.empty?
+
+      raise InvalidResponseError, "Payment Result field #{field.inspect} must be a non-empty String"
+    end
+
+    def transaction_code(payload)
+      value = webhook_string(payload, "transaction_code")
+      return value if TRANSACTION_CODE_PATTERN.match?(value)
+
+      raise InvalidResponseError, "Payment Result transaction_code has an invalid format"
+    end
+
+    def verify_token(payload)
+      value = webhook_string(payload, "verify_token")
+      return value if VERIFY_TOKEN_PATTERN.match?(value)
+
+      raise InvalidResponseError, "Payment Result verify_token has an invalid format"
+    end
+
+    def webhook_result(payload)
+      value = payload["result"]
+      return value if value.equal?(true) || value.equal?(false)
+
+      raise InvalidResponseError, "Payment Result field \"result\" must be a Boolean"
+    end
+
+    def enum(value, name, allowed, transform)
+      return nil if value.nil?
+      unless value.is_a?(String) || value.is_a?(Symbol)
+        raise ValidationError, "#{name} must be one of: #{allowed.join(", ")}"
+      end
+
+      normalized = value.to_s.public_send(transform)
+      return normalized.freeze if allowed.include?(normalized)
+
+      raise ValidationError, "#{name} must be one of: #{allowed.join(", ")}"
+    end
+    private_class_method :enum
+  end
+end

data/lib/nodex_pay/version.rb

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

data/lib/nodex_pay.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "nodex_pay/version"
+require_relative "nodex_pay/errors"
+require_relative "nodex_pay/models"
+require_relative "nodex_pay/amount_serializer"
+require_relative "nodex_pay/validator"
+require_relative "nodex_pay/signer"
+require_relative "nodex_pay/transport"
+require_relative "nodex_pay/client"
+