airwallex-ruby 0.1.0

data/docs/airwallex-research.md

@@ -0,0 +1,78 @@
+# Airwallex API Research
+
+Notes for building the unofficial `airwallex-ruby` SDK. Phase 1 uses this document only — no live API calls yet.
+
+## Official documentation
+
+- API reference: https://www.airwallex.com/docs/api
+- Authentication: https://www.airwallex.com/docs/api/authentication/api_access/login
+- Developer tools: https://www.airwallex.com/docs/developer-tools/api/quickstart-with-postman
+- Manage API keys: https://www.airwallex.com/docs/developer-tools/api/manage-api-keys
+
+## Base URLs
+
+| Environment | Base URL |
+|-------------|----------|
+| Sandbox (demo) | `https://api-demo.airwallex.com/api/v1` |
+| Production | `https://api.airwallex.com/api/v1` |
+
+## Authentication
+
+**Endpoint:** `POST /authentication/login`
+
+**Required headers:**
+
+- `x-client-id` — Airwallex Client ID
+- `x-api-key` — Airwallex API key
+
+**Response:** JSON with `token` and `expires_at`. Use the token as `Authorization: Bearer <token>` on subsequent requests.
+
+**Implementation notes:**
+
+- Do not call the login endpoint before every request.
+- Cache the token in memory and reuse it until `expires_at`.
+- Refresh only when expired or after a 401 response.
+
+Optional header for scoped keys:
+
+- `x-login-as` — target account ID when the API key is scoped to multiple accounts
+
+## Current implemented resources
+
+**Implemented:**
+
+- Authentication
+- PaymentIntents
+- Refunds
+- Webhook verification
+- Rails initializer generator
+
+**Planned:**
+
+- PaymentIntent confirm/capture
+- Customers
+- PaymentConsents
+- Transfers
+- Balances
+- Transactions
+
+## Planned resources (initial scope)
+
+| Resource | Purpose |
+|----------|---------|
+| Authentication | Obtain and manage access tokens |
+| PaymentIntents | Payment acceptance — create, confirm, capture, cancel |
+| Refunds | Refund captured payments |
+| Webhooks | Verify webhook signatures and parse events |
+| Balances | Query multi-currency account balances |
+| Transfers | Payouts to beneficiaries |
+
+## Phase roadmap
+
+Phases 1–10 are complete (foundation, HTTP client, authentication, PaymentIntents, Refunds, idempotency, webhooks, Rails integration). Phase 11 covers documentation and developer experience. Future phases add more API resources and integration test mode.
+
+## References
+
+- Postman collection uses API version header `x-api-version` (e.g. `2025-11-11`)
+- Write operations typically require a `request_id` (UUID) for idempotency
+- Sandbox file uploads use `https://files-demo.airwallex.com`; production uses `https://files.airwallex.com`

data/docs/release.md

@@ -0,0 +1,66 @@
+# Release Checklist
+
+## Before release
+
+- bundle install
+- bundle exec rspec
+- bundle exec rubocop
+- bundle exec rake build
+- gem install ./pkg/airwallex-ruby-0.1.0.gem
+- irb
+- require "airwallex"
+- Airwallex::VERSION
+
+## Git release
+
+- git status
+- git add .
+- git commit -m "Prepare v0.1.0 release"
+- git push origin develop
+
+Publishing a GitHub Release from **develop** triggers the [Release workflow](../.github/workflows/release.yml), which:
+
+1. Merges `develop` into `master`
+2. Runs RuboCop and RSpec
+3. Builds the gem
+4. Publishes to RubyGems
+5. Attaches the `.gem` file to the GitHub Release
+
+### Create the release on GitHub
+
+1. Open **Releases → Draft a new release**
+2. Set **Target** to `develop`
+3. Create tag `v0.1.0` (must match `Airwallex::VERSION`)
+4. Add release notes and click **Publish release**
+
+### GitHub Actions setup
+
+Preferred: configure [RubyGems trusted publishing](https://guides.rubygems.org/trusted-publishing/) for this repository with workflow file `release.yml`.
+
+Fallback: add a repository secret:
+
+| Secret | Description |
+|--------|-------------|
+| `RUBYGEMS_API_KEY` | RubyGems API key with push access |
+
+Because this gem sets `rubygems_mfa_required`, create the API key at [rubygems.org](https://rubygems.org/sign_in) after MFA is enabled. The key must include push permission for `airwallex-ruby`.
+
+Manual release retry (without publishing a new GitHub Release):
+
+1. Open **Actions → Release → Run workflow**
+2. Enter the tag (for example `v0.1.0`)
+
+The workflow verifies that the tag matches `Airwallex::VERSION` before publishing.
+
+## RubyGems release
+
+- gem push pkg/airwallex-ruby-0.1.0.gem
+
+Only publish after final review.
+
+## Post-release verification
+
+- gem install airwallex-ruby
+- irb
+- require "airwallex"
+- Airwallex::VERSION

data/examples/basic_configuration.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Basic global configuration and client access.
+#
+# Usage:
+#   AIRWALLEX_CLIENT_ID=... AIRWALLEX_API_KEY=... ruby examples/basic_configuration.rb
+
+require "airwallex"
+
+Airwallex.configure do |config|
+  config.client_id = ENV["AIRWALLEX_CLIENT_ID"]
+  config.api_key = ENV["AIRWALLEX_API_KEY"]
+  config.login_as = ENV["AIRWALLEX_LOGIN_AS"]
+  config.environment = :demo
+  config.timeout = 30
+  config.open_timeout = 10
+end
+
+client = Airwallex.client
+
+puts "Airwallex client ready (#{client.environment} environment)"

data/examples/payment_intent_create.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Create a PaymentIntent with an idempotency key.
+#
+# Usage:
+#   AIRWALLEX_CLIENT_ID=... AIRWALLEX_API_KEY=... ruby examples/payment_intent_create.rb
+
+require "airwallex"
+
+client = Airwallex::Client.new(
+  client_id: ENV["AIRWALLEX_CLIENT_ID"],
+  api_key: ENV["AIRWALLEX_API_KEY"],
+  login_as: ENV["AIRWALLEX_LOGIN_AS"],
+  environment: :demo
+)
+
+payment_intent = client.payment_intents.create(
+  {
+    amount: 1000,
+    currency: "PHP",
+    merchant_order_id: "ORDER-1001",
+    return_url: "https://example.com/return"
+  },
+  idempotency_key: "order-1001-create"
+)
+
+puts payment_intent["id"]
+puts payment_intent["client_secret"]

data/examples/rails_webhook_controller.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Example Airwallex webhook controller for Rails.
+# Copy into app/controllers/airwallex_webhooks_controller.rb
+#
+# Route (config/routes.rb):
+#   post "/webhooks/airwallex", to: "airwallex_webhooks#create"
+#
+# class AirwallexWebhooksController < ApplicationController
+#   skip_before_action :verify_authenticity_token
+#
+#   def create
+#     event = Airwallex::Webhook.construct_event(
+#       payload: request.body.read,
+#       signature: request.headers["x-signature"],
+#       timestamp: request.headers["x-timestamp"],
+#       secret: webhook_secret
+#     )
+#
+#     case event["name"]
+#     when "payment_intent.succeeded"
+#       # handle payment success
+#     when "refund.accepted"
+#       # handle refund accepted
+#     end
+#
+#     head :ok
+#   rescue Airwallex::WebhookSignatureError, Airwallex::InvalidResponseError
+#     head :bad_request
+#   end
+#
+#   private
+#
+#   def webhook_secret
+#     Rails.application.credentials.dig(:airwallex, :webhook_secret) ||
+#       ENV.fetch("AIRWALLEX_WEBHOOK_SECRET")
+#   end
+# end

data/examples/refund_create.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Create a refund with an idempotency key.
+#
+# Usage:
+#   AIRWALLEX_CLIENT_ID=... AIRWALLEX_API_KEY=... ruby examples/refund_create.rb
+
+require "airwallex"
+
+client = Airwallex::Client.new(
+  client_id: ENV["AIRWALLEX_CLIENT_ID"],
+  api_key: ENV["AIRWALLEX_API_KEY"],
+  login_as: ENV["AIRWALLEX_LOGIN_AS"],
+  environment: :demo
+)
+
+refund = client.refunds.create(
+  {
+    payment_intent_id: "int_123",
+    amount: 500,
+    reason: "requested_by_customer",
+    metadata: {
+      order_id: "ORDER-1001"
+    }
+  },
+  idempotency_key: "order-1001-refund-1"
+)
+
+puts refund["id"]

data/examples/webhook_verification.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Verify an Airwallex webhook payload and parse the event.
+#
+# Usage:
+#   AIRWALLEX_WEBHOOK_SECRET=... ruby examples/webhook_verification.rb
+
+require "airwallex"
+require "openssl"
+
+secret = ENV.fetch("AIRWALLEX_WEBHOOK_SECRET")
+payload = '{"name":"payment_intent.succeeded","data":{}}'
+timestamp = Time.now.to_i.to_s
+signature = OpenSSL::HMAC.hexdigest("SHA256", secret, timestamp + payload)
+
+event = Airwallex::Webhook.construct_event(
+  payload: payload,
+  signature: signature,
+  timestamp: timestamp,
+  secret: secret
+)
+
+puts event["name"]

data/lib/airwallex/client.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require "json"
+require "faraday"
+require "time"
+
+module Airwallex
+  class Client
+    DEFAULT_HEADERS = {
+      "Content-Type" => "application/json",
+      "Accept" => "application/json"
+    }.freeze
+
+    TOKEN_EXPIRY_BUFFER = 60
+
+    attr_reader :client_id, :api_key, :login_as, :environment, :timeout, :open_timeout, :logger,
+                :access_token, :token_expires_at
+
+    def initialize(**options)
+      config = Airwallex.configuration
+
+      @client_id = options.fetch(:client_id, config.client_id)
+      @api_key = options.fetch(:api_key, config.api_key)
+      @login_as = options.key?(:login_as) ? options[:login_as] : config.login_as
+      @environment = Configuration.validate_environment!(options.fetch(:environment, config.environment))
+      @timeout = options.fetch(:timeout, config.timeout)
+      @open_timeout = options.fetch(:open_timeout, config.open_timeout)
+      @logger = options.fetch(:logger, config.logger)
+      @access_token = nil
+      @token_expires_at = nil
+    end
+
+    def base_url
+      Configuration::ENVIRONMENTS.fetch(environment)
+    end
+
+    def authentication
+      @authentication ||= Resources::Authentication.new(self)
+    end
+
+    def payment_intents
+      @payment_intents ||= Resources::PaymentIntents.new(self)
+    end
+
+    def refunds
+      @refunds ||= Resources::Refunds.new(self)
+    end
+
+    def authenticate
+      authentication.login
+    end
+
+    def authenticated?
+      !access_token.nil? && !token_expired?
+    end
+
+    def auth_headers
+      { "Authorization" => "Bearer #{access_token}" }
+    end
+
+    def get(path, params = {}, headers = {}, authenticated: true)
+      request(:get, path, params: params, headers: headers, authenticated: authenticated)
+    end
+
+    def post(path, body = {}, headers = {}, authenticated: true, idempotency_key: nil)
+      validate_idempotency_key!(idempotency_key)
+      request(:post, path, body: body, headers: headers, authenticated: authenticated,
+                           idempotency_key: idempotency_key)
+    end
+
+    def patch(path, body = {}, headers = {}, authenticated: true, idempotency_key: nil)
+      validate_idempotency_key!(idempotency_key)
+      request(:patch, path, body: body, headers: headers, authenticated: authenticated,
+                            idempotency_key: idempotency_key)
+    end
+
+    def delete(path, params = {}, headers = {}, authenticated: true)
+      request(:delete, path, params: params, headers: headers, authenticated: authenticated)
+    end
+
+    def validate_credentials!
+      raise ConfigurationError, "client_id is required" if client_id.nil? || client_id.to_s.empty?
+      raise ConfigurationError, "api_key is required" if api_key.nil? || api_key.to_s.empty?
+    end
+
+    def store_token!(response)
+      token = response["token"]
+      raise AuthenticationError, "Authentication response missing token" if token.nil? || token.to_s.empty?
+
+      @access_token = token
+      @token_expires_at = parse_expires_at(response["expires_at"])
+    end
+
+    private
+
+    def request(method, path, params: nil, body: nil, headers: {}, authenticated: true,
+                idempotency_key: nil)
+      ensure_authenticated! if authenticated
+
+      response = connection.run_request(
+        method,
+        request_url(path),
+        body,
+        merge_headers(headers, authenticated: authenticated, idempotency_key: idempotency_key)
+      ) do |req|
+        req.params.update(params) if params && !params.empty?
+      end
+
+      handle_response(response)
+    rescue Faraday::TimeoutError => e
+      raise TimeoutError, e.message
+    rescue Faraday::ConnectionFailed => e
+      raise TimeoutError, e.message if timeout_error?(e)
+
+      raise
+    end
+
+    def ensure_authenticated!
+      authenticate unless authenticated?
+    end
+
+    def token_expired?
+      return true if access_token.nil? || token_expires_at.nil?
+
+      Time.now >= (token_expires_at - TOKEN_EXPIRY_BUFFER)
+    end
+
+    def parse_expires_at(value)
+      if value.nil? || value.to_s.strip.empty?
+        raise AuthenticationError, "Authentication response has invalid expires_at"
+      end
+
+      case value
+      when Time
+        value
+      when Integer, Float
+        Time.at(value)
+      when String
+        Time.parse(value)
+      else
+        raise AuthenticationError, "Authentication response has invalid expires_at"
+      end
+    rescue ::ArgumentError, ::TypeError
+      raise AuthenticationError, "Authentication response has invalid expires_at"
+    end
+
+    def timeout_error?(error)
+      cause = error.wrapped_exception
+      cause.is_a?(Net::OpenTimeout) ||
+        cause.is_a?(Net::ReadTimeout) ||
+        cause.is_a?(Timeout::Error) ||
+        error.message.match?(/timeout|timed out/i)
+    end
+
+    def request_url(path)
+      path = path.to_s
+      return path if path.start_with?("http://", "https://")
+
+      path = "/#{path}" unless path.start_with?("/")
+      "#{base_url}#{path}"
+    end
+
+    def connection
+      @connection ||= Faraday.new do |conn|
+        conn.options.timeout = timeout
+        conn.options.open_timeout = open_timeout
+        conn.request :json
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def merge_headers(headers, authenticated:, idempotency_key: nil)
+      merged = DEFAULT_HEADERS.merge(headers)
+      merged = merged.merge(auth_headers) if authenticated
+      merged["x-idempotency-key"] = idempotency_key if idempotency_key
+      merged
+    end
+
+    def validate_idempotency_key!(idempotency_key)
+      return if idempotency_key.nil?
+
+      return if idempotency_key.is_a?(String) && !idempotency_key.strip.empty?
+
+      raise ArgumentError, "idempotency_key must be a non-empty String"
+    end
+
+    def handle_response(response)
+      parsed_body = parse_body(response.body)
+
+      return parsed_body if response.status.between?(200, 299)
+
+      HTTPError.raise_for_response!(response.status, parsed_body, response.body)
+    end
+
+    def parse_body(body)
+      return {} if body.nil? || body.to_s.strip.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError => e
+      raise InvalidResponseError, "Invalid JSON response: #{e.message}"
+    end
+  end
+end

data/lib/airwallex/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Airwallex
+  class Configuration
+    ENVIRONMENTS = {
+      demo: "https://api-demo.airwallex.com/api/v1",
+      production: "https://api.airwallex.com/api/v1"
+    }.freeze
+
+    attr_accessor :client_id, :api_key, :login_as, :timeout, :open_timeout, :logger
+    attr_reader :environment
+
+    def initialize
+      @environment = :demo
+      @timeout = 30
+      @open_timeout = 10
+      @logger = nil
+    end
+
+    def environment=(value)
+      self.class.validate_environment!(value)
+      @environment = value
+    end
+
+    def base_url
+      ENVIRONMENTS.fetch(environment)
+    end
+
+    alias api_base_url base_url
+
+    def self.validate_environment!(environment)
+      return environment if ENVIRONMENTS.key?(environment)
+
+      valid = ENVIRONMENTS.keys.map(&:inspect).join(", ")
+      raise ConfigurationError, "Invalid environment: #{environment.inspect}. Valid environments are: #{valid}"
+    end
+  end
+end

data/lib/airwallex/errors.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Airwallex
+  class Error < StandardError
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class ArgumentError < Error
+  end
+
+  class AuthenticationError < Error
+  end
+
+  class HTTPError < Error
+    attr_reader :status, :code, :source, :details, :response_body
+
+    def initialize(message = nil, **attrs)
+      super(message)
+      @status = attrs[:status]
+      @code = attrs[:code]
+      @source = attrs[:source]
+      @details = attrs[:details]
+      @response_body = attrs[:response_body]
+    end
+
+    def self.raise_for_response!(status, parsed_body, raw_body)
+      fields = parsed_body.is_a?(Hash) ? parsed_body : {}
+      raise error_class_for(status).new(
+        extract_message(parsed_body, status),
+        status: status,
+        code: fields["code"],
+        source: fields["source"],
+        details: fields["details"],
+        response_body: raw_body
+      )
+    end
+
+    def self.error_class_for(status)
+      return ServerError if status.between?(500, 599)
+
+      status_error_map.fetch(status, HTTPError)
+    end
+
+    def self.extract_message(parsed_body, status)
+      return parsed_body["message"] if parsed_body.is_a?(Hash) && parsed_body["message"]
+      return parsed_body["code"] if parsed_body.is_a?(Hash) && parsed_body["code"]
+
+      "HTTP #{status}"
+    end
+
+    def self.status_error_map
+      @status_error_map ||= {
+        400 => BadRequestError,
+        401 => UnauthorizedError,
+        403 => ForbiddenError,
+        404 => NotFoundError,
+        409 => ConflictError,
+        429 => RateLimitError
+      }.freeze
+    end
+
+    private_class_method :error_class_for, :extract_message, :status_error_map
+  end
+
+  class BadRequestError < HTTPError; end
+  class UnauthorizedError < HTTPError; end
+  class ForbiddenError < HTTPError; end
+  class NotFoundError < HTTPError; end
+  class ConflictError < HTTPError; end
+  class RateLimitError < HTTPError; end
+  class ServerError < HTTPError; end
+  class TimeoutError < HTTPError; end
+  class InvalidResponseError < HTTPError; end
+  class WebhookSignatureError < Error; end
+end

data/lib/airwallex/railtie.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Airwallex
+  class Railtie < Rails::Railtie
+  end
+end

data/lib/airwallex/resources/authentication.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Airwallex
+  module Resources
+    class Authentication < BaseResource
+      LOGIN_PATH = "/authentication/login"
+
+      def login
+        client.validate_credentials!
+
+        response = post(LOGIN_PATH, {}, authentication_headers, authenticated: false)
+        client.store_token!(response)
+        response
+      end
+
+      private
+
+      def authentication_headers
+        headers = {
+          "x-client-id" => client.client_id,
+          "x-api-key" => client.api_key
+        }
+        headers["x-login-as"] = client.login_as if client.login_as
+        headers
+      end
+    end
+  end
+end

data/lib/airwallex/resources/base_resource.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Airwallex
+  module Resources
+    class BaseResource
+      attr_reader :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      def get(path, params = {}, headers = {}, **options)
+        client.get(path, params, headers, **options)
+      end
+
+      def post(path, body = {}, headers = {}, **options)
+        client.post(path, body, headers, **options)
+      end
+
+      def patch(path, body = {}, headers = {}, **options)
+        client.patch(path, body, headers, **options)
+      end
+
+      def delete(path, params = {}, headers = {}, **options)
+        client.delete(path, params, headers, **options)
+      end
+
+      def validate_idempotency_key!(idempotency_key)
+        return if idempotency_key.nil?
+
+        return if idempotency_key.is_a?(String) && !idempotency_key.strip.empty?
+
+        raise Airwallex::ArgumentError, "idempotency_key must be a non-empty String"
+      end
+
+      def validate_id!(id, name = "id")
+        raise Airwallex::ArgumentError, "#{name} is required" if id.nil? || id.to_s.strip.empty?
+      end
+
+      def validate_params!(params)
+        raise Airwallex::ArgumentError, "params must be a Hash" unless params.is_a?(Hash)
+      end
+    end
+  end
+end