airwallex 0.1.0

data/lib/airwallex/client.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/multipart"
+require "faraday/retry"
+require "json"
+
+module Airwallex
+  class Client
+    attr_reader :config, :access_token, :token_expires_at
+
+    def initialize(config = Airwallex.configuration)
+      @config = config
+      @config.validate!
+      @access_token = nil
+      @token_expires_at = nil
+      @token_mutex = Mutex.new
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: config.api_url) do |conn|
+        conn.request :json
+        conn.request :multipart
+        conn.request :retry, retry_options
+        conn.response :json, content_type: /\bjson$/
+        conn.response :logger, config.logger, { headers: true, bodies: true } if config.logger
+
+        conn.headers["Content-Type"] = "application/json"
+        conn.headers["User-Agent"] = user_agent
+        conn.headers["x-api-version"] = config.api_version
+
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def get(path, params = {}, headers = {})
+      request(:get, path, params, headers)
+    end
+
+    def post(path, body = {}, headers = {})
+      request(:post, path, body, headers)
+    end
+
+    def put(path, body = {}, headers = {})
+      request(:put, path, body, headers)
+    end
+
+    def patch(path, body = {}, headers = {})
+      request(:patch, path, body, headers)
+    end
+
+    def delete(path, params = {}, headers = {})
+      request(:delete, path, params, headers)
+    end
+
+    def authenticate!
+      @token_mutex.synchronize do
+        response = connection.post("/api/v1/authentication/login") do |req|
+          req.headers["x-client-id"] = config.client_id
+          req.headers["x-api-key"] = config.api_key
+          req.headers.delete("Authorization")
+        end
+
+        handle_response_errors(response)
+
+        data = response.body
+        @access_token = data["token"]
+        @token_expires_at = Time.now + 1800 # 30 minutes
+
+        @access_token
+      end
+    end
+
+    def token_expired?
+      return true if access_token.nil? || token_expires_at.nil?
+
+      # Refresh if token expires in less than 5 minutes
+      Time.now >= (token_expires_at - 300)
+    end
+
+    def ensure_authenticated!
+      authenticate! if token_expired?
+    end
+
+    private
+
+    def request(method, path, data, headers)
+      ensure_authenticated!
+
+      response = connection.public_send(method) do |req|
+        req.url(path)
+        req.headers.merge!(headers)
+        req.headers["Authorization"] = "Bearer #{access_token}"
+
+        case method
+        when :get, :delete
+          req.params = data
+        when :post, :put, :patch
+          req.body = data
+        end
+      end
+
+      handle_response_errors(response)
+      response.body
+    end
+
+    def handle_response_errors(response)
+      return if response.success?
+
+      raise Error.from_response(response)
+    end
+
+    def retry_options
+      {
+        max: 3,
+        interval: 0.5,
+        interval_randomness: 0.5,
+        backoff_factor: 2,
+        methods: %i[get delete],
+        exceptions: [
+          Faraday::TimeoutError,
+          Faraday::ConnectionFailed
+        ],
+        retry_statuses: [429, 500, 502, 503, 504]
+      }
+    end
+
+    def user_agent
+      "Airwallex-Ruby/#{Airwallex::VERSION} Ruby/#{RUBY_VERSION}"
+    end
+  end
+end

data/lib/airwallex/configuration.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Airwallex
+  class Configuration
+    attr_accessor :api_key, :client_id, :api_version, :logger, :log_level
+    attr_reader :environment
+
+    SANDBOX_API_URL = "https://api-demo.airwallex.com"
+    PRODUCTION_API_URL = "https://api.airwallex.com"
+    SANDBOX_FILES_URL = "https://files-demo.airwallex.com"
+    PRODUCTION_FILES_URL = "https://files.airwallex.com"
+
+    DEFAULT_API_VERSION = "2024-09-27"
+    VALID_ENVIRONMENTS = %i[sandbox production].freeze
+
+    def initialize
+      @environment = :sandbox
+      @api_version = DEFAULT_API_VERSION
+      @log_level = :info
+    end
+
+    def api_url
+      case environment
+      when :sandbox
+        SANDBOX_API_URL
+      when :production
+        PRODUCTION_API_URL
+      else
+        raise ConfigurationError, "Invalid environment: #{environment}. Must be :sandbox or :production"
+      end
+    end
+
+    def files_url
+      case environment
+      when :sandbox
+        SANDBOX_FILES_URL
+      when :production
+        PRODUCTION_FILES_URL
+      else
+        raise ConfigurationError, "Invalid environment: #{environment}. Must be :sandbox or :production"
+      end
+    end
+
+    def environment=(env)
+      unless VALID_ENVIRONMENTS.include?(env)
+        raise ConfigurationError, "Invalid environment: #{env}. Must be one of #{VALID_ENVIRONMENTS.join(", ")}"
+      end
+
+      @environment = env
+    end
+
+    def validate!
+      errors = []
+      errors << "api_key is required" if api_key.nil? || api_key.empty?
+      errors << "client_id is required" if client_id.nil? || client_id.empty?
+      errors << "environment must be :sandbox or :production" unless VALID_ENVIRONMENTS.include?(environment)
+
+      raise ConfigurationError, errors.join(", ") unless errors.empty?
+
+      true
+    end
+
+    def configured?
+      !api_key.nil? && !client_id.nil? && VALID_ENVIRONMENTS.include?(environment)
+    end
+  end
+end

data/lib/airwallex/errors.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Airwallex
+  class Error < StandardError
+    attr_reader :code, :message, :param, :details, :http_status
+
+    def initialize(message = nil, code: nil, param: nil, details: nil, http_status: nil)
+      @code = code
+      @message = message
+      @param = param
+      @details = details
+      @http_status = http_status
+      super(message)
+    end
+
+    def self.from_response(response)
+      body = parse_body(response.body)
+      status = response.status
+
+      error_class = error_class_for_status(status)
+      error_class.new(
+        body["message"],
+        code: body["code"],
+        param: body["source"],
+        details: body["details"],
+        http_status: status
+      )
+    end
+
+    def self.parse_body(body)
+      return {} if body.nil? || body.empty?
+      return body if body.is_a?(Hash)
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      { "message" => body }
+    end
+
+    def self.error_class_for_status(status)
+      case status
+      when 400 then BadRequestError
+      when 401 then AuthenticationError
+      when 403 then PermissionError
+      when 404 then NotFoundError
+      when 429 then RateLimitError
+      when 500..599 then APIError
+      else Error
+      end
+    end
+
+    private_class_method :parse_body, :error_class_for_status
+  end
+
+  class ConfigurationError < Error; end
+  class BadRequestError < Error; end
+  class AuthenticationError < Error; end
+  class PermissionError < Error; end
+  class NotFoundError < Error; end
+  class RateLimitError < Error; end
+  class APIError < Error; end
+  class InsufficientFundsError < Error; end
+  class SCARequiredError < PermissionError; end
+  class SignatureVerificationError < Error; end
+end

data/lib/airwallex/list_object.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Airwallex
+  class ListObject
+    include Enumerable
+
+    attr_reader :data, :has_more, :next_cursor
+
+    def initialize(data:, has_more:, resource_class:, next_cursor: nil, params: {})
+      @data = data.map { |item| resource_class.new(item) }
+      @has_more = has_more
+      @next_cursor = next_cursor
+      @resource_class = resource_class
+      @params = params
+    end
+
+    def each(&)
+      @data.each(&)
+    end
+
+    def [](index)
+      @data[index]
+    end
+
+    def size
+      @data.size
+    end
+
+    alias length size
+    alias count size
+
+    def empty?
+      @data.empty?
+    end
+
+    def first
+      @data.first
+    end
+
+    def last
+      @data.last
+    end
+
+    # Fetch the next page of results
+    def next_page
+      return nil unless @has_more
+
+      next_params = @params.dup
+
+      if @next_cursor
+        # Cursor-based pagination
+        next_params[:next_cursor] = @next_cursor
+      else
+        # Offset-based pagination
+        page_size = @params[:page_size] || @params[:limit] || 20
+        current_offset = @params[:offset] || 0
+        next_params[:offset] = current_offset + page_size
+      end
+
+      @resource_class.list(next_params)
+    end
+
+    # Automatically iterate through all pages
+    def auto_paging_each(&block)
+      return enum_for(:auto_paging_each) unless block_given?
+
+      page = self
+      loop do
+        page.each(&block)
+        break unless page.has_more
+
+        page = page.next_page
+        break if page.nil? || page.empty?
+      end
+    end
+
+    def to_a
+      @data
+    end
+
+    def inspect
+      "#<#{self.class}[#{@data.size}] has_more=#{@has_more}>"
+    end
+  end
+end

data/lib/airwallex/middleware/auth_refresh.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Airwallex
+  module Middleware
+    class AuthRefresh < Faraday::Middleware
+      def initialize(app, client)
+        super(app)
+        @client = client
+      end
+
+      def call(env)
+        # Skip authentication refresh for login endpoint
+        return @app.call(env) if env[:url].path.include?("/authentication/login")
+
+        # Ensure token is valid before making request
+        @client.ensure_authenticated! unless env[:url].path.include?("/authentication/")
+
+        response = @app.call(env)
+
+        # If we get a 401, try refreshing the token and retrying once
+        if response.status == 401 && !env[:request].fetch(:auth_retry, false)
+          @client.authenticate!
+          env[:request][:auth_retry] = true
+          env[:request_headers]["Authorization"] = "Bearer #{@client.access_token}"
+          response = @app.call(env)
+        end
+
+        response
+      end
+    end
+  end
+end

data/lib/airwallex/middleware/idempotency.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Airwallex
+  module Middleware
+    class Idempotency < Faraday::Middleware
+      IDEMPOTENT_METHODS = %i[post put patch].freeze
+
+      def call(env)
+        inject_request_id(env) if idempotent_request?(env)
+
+        @app.call(env)
+      end
+
+      private
+
+      def idempotent_request?(env)
+        IDEMPOTENT_METHODS.include?(env[:method]) && env[:body].is_a?(Hash)
+      end
+
+      def inject_request_id(env)
+        body = env[:body]
+
+        return if body.key?("request_id") || body.key?(:request_id)
+
+        body[:request_id] = Airwallex::Util.generate_idempotency_key
+      end
+    end
+  end
+end

data/lib/airwallex/resources/beneficiary.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Airwallex
+  class Beneficiary < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+    extend APIOperations::Delete
+
+    def self.resource_path
+      "/api/v1/beneficiaries"
+    end
+  end
+end

data/lib/airwallex/resources/payment_intent.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Airwallex
+  class PaymentIntent < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+    include APIOperations::Update
+
+    def self.resource_path
+      "/api/v1/pa/payment_intents"
+    end
+
+    # Confirm the payment intent with payment method details
+    def confirm(params = {})
+      response = Airwallex.client.post(
+        "#{self.class.resource_path}/#{id}/confirm",
+        params
+      )
+      refresh_from(response)
+      self
+    end
+
+    # Cancel the payment intent
+    def cancel(params = {})
+      response = Airwallex.client.post(
+        "#{self.class.resource_path}/#{id}/cancel",
+        params
+      )
+      refresh_from(response)
+      self
+    end
+
+    # Capture an authorized payment
+    def capture(params = {})
+      response = Airwallex.client.post(
+        "#{self.class.resource_path}/#{id}/capture",
+        params
+      )
+      refresh_from(response)
+      self
+    end
+  end
+end

data/lib/airwallex/resources/transfer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Airwallex
+  class Transfer < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+
+    def self.resource_path
+      "/api/v1/transfers"
+    end
+
+    # Cancel a pending transfer
+    def cancel
+      response = Airwallex.client.post(
+        "#{self.class.resource_path}/#{id}/cancel",
+        {}
+      )
+      refresh_from(response)
+      self
+    end
+  end
+end

data/lib/airwallex/util.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+require "bigdecimal"
+
+module Airwallex
+  module Util
+    module_function
+
+    def generate_idempotency_key
+      SecureRandom.uuid
+    end
+
+    def format_date_time(value)
+      case value
+      when Time, DateTime
+        value.utc.iso8601
+      when Date
+        value.to_time.utc.iso8601
+      when String
+        value
+      else
+        raise ArgumentError, "Cannot format #{value.class} as ISO 8601"
+      end
+    end
+
+    def parse_date_time(value)
+      return nil if value.nil?
+      return value if value.is_a?(Time)
+
+      Time.iso8601(value)
+    rescue ArgumentError
+      Time.parse(value)
+    end
+
+    def symbolize_keys(hash)
+      return hash unless hash.is_a?(Hash)
+
+      hash.transform_keys(&:to_sym)
+    end
+
+    def deep_symbolize_keys(hash)
+      return hash unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) do |(key, value), result|
+        result[key.to_sym] = value.is_a?(Hash) ? deep_symbolize_keys(value) : value
+      end
+    end
+
+    def to_money(value)
+      return value if value.is_a?(BigDecimal)
+      return BigDecimal("0") if value.nil?
+
+      BigDecimal(value.to_s)
+    end
+  end
+end

data/lib/airwallex/version.rb

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

data/lib/airwallex/webhook.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Airwallex
+  module Webhook
+    DEFAULT_TOLERANCE = 300 # 5 minutes
+
+    module_function
+
+    def construct_event(payload, signature, timestamp, secret:, tolerance: DEFAULT_TOLERANCE)
+      verify_signature(payload, signature, timestamp, secret, tolerance)
+
+      data = JSON.parse(payload)
+      Event.new(data)
+    rescue JSON::ParserError => e
+      raise SignatureVerificationError, "Invalid payload: #{e.message}"
+    end
+
+    def verify_signature(payload, signature, timestamp, secret, tolerance)
+      verify_timestamp(timestamp, tolerance)
+
+      expected_signature = compute_signature(timestamp, payload, secret)
+
+      unless secure_compare(expected_signature, signature)
+        raise SignatureVerificationError, "Signature verification failed"
+      end
+
+      true
+    end
+
+    def compute_signature(timestamp, payload, secret)
+      data = "#{timestamp}#{payload}"
+      OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), secret, data)
+    end
+
+    def verify_timestamp(timestamp, tolerance)
+      current_time = Time.now.to_i
+      timestamp_int = timestamp.to_i
+
+      if (current_time - timestamp_int).abs > tolerance
+        raise SignatureVerificationError, "Timestamp outside tolerance (#{tolerance}s)"
+      end
+
+      true
+    end
+
+    def secure_compare(a, b)
+      return false if a.nil? || b.nil? || a.bytesize != b.bytesize
+
+      OpenSSL.fixed_length_secure_compare(a, b)
+    end
+
+    private_class_method :compute_signature, :verify_timestamp, :secure_compare
+
+    class Event
+      attr_reader :id, :type, :data, :created_at
+
+      def initialize(attributes = {})
+        @id = attributes["id"]
+        @type = attributes["type"]
+        @data = attributes["data"]
+        @created_at = attributes["created_at"]
+      end
+    end
+  end
+end

data/lib/airwallex.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "airwallex/version"
+require_relative "airwallex/errors"
+require_relative "airwallex/configuration"
+require_relative "airwallex/util"
+require_relative "airwallex/client"
+require_relative "airwallex/webhook"
+require_relative "airwallex/middleware/idempotency"
+require_relative "airwallex/middleware/auth_refresh"
+
+# API Operations
+require_relative "airwallex/api_operations/create"
+require_relative "airwallex/api_operations/retrieve"
+require_relative "airwallex/api_operations/list"
+require_relative "airwallex/api_operations/update"
+require_relative "airwallex/api_operations/delete"
+
+# Core classes
+require_relative "airwallex/list_object"
+require_relative "airwallex/api_resource"
+
+# Resources
+require_relative "airwallex/resources/payment_intent"
+require_relative "airwallex/resources/transfer"
+require_relative "airwallex/resources/beneficiary"
+
+module Airwallex
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def client
+      @client ||= Client.new(configuration)
+    end
+
+    def reset!
+      @configuration = Configuration.new
+      @client = nil
+    end
+  end
+end

data/sig/airwallex.rbs

@@ -0,0 +1,4 @@
+module Airwallex
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end