airwallex 0.2.0 → 0.6.0

data/lib/airwallex/resources/quote.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Quote resource for locked exchange rates
+  #
+  # Create quotes to lock exchange rates for a short period (typically 30-60 seconds).
+  # Use quotes to guarantee the rate when executing conversions.
+  #
+  # @example Create a quote
+  #   quote = Airwallex::Quote.create(
+  #     buy_currency: 'EUR',
+  #     sell_currency: 'USD',
+  #     sell_amount: 1000.00
+  #   )
+  #   puts "Locked rate: #{quote.client_rate}, expires: #{quote.expires_at}"
+  #
+  # @example Use quote for conversion
+  #   conversion = Airwallex::Conversion.create(quote_id: quote.id)
+  #
+  class Quote < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+
+    def self.resource_path
+      "/api/v1/fx/quotes"
+    end
+
+    # Check if quote has expired
+    #
+    # @return [Boolean] true if quote is expired
+    def expired?
+      return false unless respond_to?(:expires_at) && expires_at
+
+      Time.parse(expires_at) < Time.now
+    rescue ArgumentError
+      true
+    end
+
+    # Get seconds until expiration
+    #
+    # @return [Integer, nil] seconds remaining, 0 if expired, nil if no expiration
+    def seconds_until_expiration
+      return nil unless respond_to?(:expires_at) && expires_at
+
+      remaining = Time.parse(expires_at) - Time.now
+      [remaining.to_i, 0].max
+    rescue ArgumentError
+      0
+    end
+  end
+end

data/lib/airwallex/resources/rate.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Rate resource for real-time exchange rates
+  #
+  # Get indicative exchange rates for currency pairs.
+  # Rates are real-time but not locked - use Quote for guaranteed rates.
+  #
+  # @example Get current rate
+  #   rate = Airwallex::Rate.retrieve(buy_currency: 'EUR', sell_currency: 'USD')
+  #   puts "1 USD = #{rate.client_rate} EUR"
+  #
+  # @example Get multiple rates (Note: API may not support multiple at once)
+  #   rate = Airwallex::Rate.retrieve(
+  #     buy_currency: 'EUR',
+  #     sell_currency: 'USD'
+  #   )
+  #
+  class Rate < APIResource
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+
+    def self.resource_path
+      "/api/v1/fx/rates/current"
+    end
+
+    # Override retrieve to handle query parameters instead of ID
+    def self.retrieve(params = {})
+      response = Airwallex.client.get(resource_path, params)
+      new(response)
+    end
+  end
+end

data/lib/airwallex/resources/refund.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Airwallex
+  # Represents a refund of a payment intent
+  #
+  # Refunds can be full or partial. Multiple refunds can be created for a single
+  # payment intent as long as the total refunded amount doesn't exceed the original amount.
+  #
+  # @example Create a full refund
+  #   refund = Airwallex::Refund.create(
+  #     payment_intent_id: "pi_123",
+  #     amount: 100.00,
+  #     reason: "requested_by_customer"
+  #   )
+  #
+  # @example Create a partial refund
+  #   refund = Airwallex::Refund.create(
+  #     payment_intent_id: "pi_123",
+  #     amount: 25.00
+  #   )
+  #
+  # @example List refunds for a payment
+  #   refunds = Airwallex::Refund.list(payment_intent_id: "pi_123")
+  class Refund < APIResource
+    extend APIOperations::Create
+    extend APIOperations::Retrieve
+    extend APIOperations::List
+
+    # @return [String] API resource path for refunds
+    def self.resource_path
+      "/api/v1/pa/refunds"
+    end
+  end
+end

data/lib/airwallex/version.rb

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

data/lib/airwallex/webhook.rb

@@ -5,6 +5,8 @@ require "openssl"
 module Airwallex
   module Webhook
     DEFAULT_TOLERANCE = 300 # 5 minutes
+    # Timestamps below this are seconds, at/above are milliseconds. Valid until year 2286.
+    MS_THRESHOLD = 10_000_000_000
 
     module_function
 
@@ -37,6 +39,8 @@ module Airwallex
     def verify_timestamp(timestamp, tolerance)
       current_time = Time.now.to_i
       timestamp_int = timestamp.to_i
+      # Airwallex sends x-timestamp in milliseconds; normalize to seconds before comparing.
+      timestamp_int /= 1000 if timestamp_int > MS_THRESHOLD
 
       if (current_time - timestamp_int).abs > tolerance
         raise SignatureVerificationError, "Timestamp outside tolerance (#{tolerance}s)"
@@ -54,11 +58,11 @@ module Airwallex
     private_class_method :compute_signature, :verify_timestamp, :secure_compare
 
     class Event
-      attr_reader :id, :type, :data, :created_at
+      attr_reader :id, :name, :data, :created_at
 
       def initialize(attributes = {})
         @id = attributes["id"]
-        @type = attributes["type"]
+        @name = attributes["name"]
         @data = attributes["data"]
         @created_at = attributes["created_at"]
       end

data/lib/airwallex.rb

@@ -27,6 +27,12 @@ require_relative "airwallex/resources/beneficiary"
 require_relative "airwallex/resources/refund"
 require_relative "airwallex/resources/payment_method"
 require_relative "airwallex/resources/customer"
+require_relative "airwallex/resources/batch_transfer"
+require_relative "airwallex/resources/dispute"
+require_relative "airwallex/resources/rate"
+require_relative "airwallex/resources/quote"
+require_relative "airwallex/resources/conversion"
+require_relative "airwallex/resources/balance"
 
 module Airwallex
   class << self

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: airwallex
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Chayut Orapinpatipat
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-25 00:00:00.000000000 Z
+date: 2026-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -53,9 +53,10 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.0'
 description: A comprehensive Ruby gem for integrating with Airwallex's global payment
-  infrastructure, including payment acceptance, payouts, foreign exchange, card issuing,
-  and treasury. Features automatic authentication management, idempotency guarantees,
-  webhook verification, and unified pagination.
+  infrastructure, including payment acceptance, payouts, foreign exchange (FX rates,
+  quotes, conversions), and multi-currency balance management. Features automatic
+  authentication, idempotency guarantees, webhook verification, and unified pagination
+  across all resources.
 email:
 - chayut@sentia.com.au
 executables: []
@@ -66,16 +67,6 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- docs/internal/20251125_iteration_1_quickstart.md
-- docs/internal/20251125_iteration_1_summary.md
-- docs/internal/20251125_sprint_1_completed.md
-- docs/internal/20251125_sprint_1_plan.md
-- docs/internal/20251125_sprint_2_completed.md
-- docs/internal/20251125_sprint_2_plan.md
-- docs/internal/20251125_sprint_2_unit_tests_completed.md
-- docs/internal/20251125_v0.1.0_publication_checklist.md
-- docs/research/Airwallex API Endpoint Research.md
-- docs/research/Airwallex API Research for Ruby Gem.md
 - lib/airwallex.rb
 - lib/airwallex/api_operations/create.rb
 - lib/airwallex/api_operations/delete.rb
@@ -89,8 +80,17 @@ files:
 - lib/airwallex/list_object.rb
 - lib/airwallex/middleware/auth_refresh.rb
 - lib/airwallex/middleware/idempotency.rb
+- lib/airwallex/resources/balance.rb
+- lib/airwallex/resources/batch_transfer.rb
 - lib/airwallex/resources/beneficiary.rb
+- lib/airwallex/resources/conversion.rb
+- lib/airwallex/resources/customer.rb
+- lib/airwallex/resources/dispute.rb
 - lib/airwallex/resources/payment_intent.rb
+- lib/airwallex/resources/payment_method.rb
+- lib/airwallex/resources/quote.rb
+- lib/airwallex/resources/rate.rb
+- lib/airwallex/resources/refund.rb
 - lib/airwallex/resources/transfer.rb
 - lib/airwallex/util.rb
 - lib/airwallex/version.rb
@@ -122,7 +122,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: Production-grade Ruby client for the Airwallex API

data/docs/internal/20251125_iteration_1_quickstart.md

@@ -1,130 +0,0 @@
-# Iteration 1 - Quick Start
-
-**Sprint 1, Iteration 1**  
-**Date:** 25 November 2025  
-**Status:** ✅ Complete
-
-## What Was Built
-
-Core infrastructure for the Airwallex Ruby gem including:
-
-1. ✅ Complete directory structure
-2. ✅ Configuration management (sandbox/production)
-3. ✅ HTTP client with Faraday
-4. ✅ Bearer token authentication with auto-refresh
-5. ✅ Comprehensive error handling
-6. ✅ Automatic idempotency
-7. ✅ Webhook signature verification
-8. ✅ Utility helpers
-9. ✅ Zero Rubocop offenses
-
-## Quick Test
-
-```ruby
-require 'airwallex'
-
-# Configure the gem
-Airwallex.configure do |config|
-  config.api_key = 'your_api_key'
-  config.client_id = 'your_client_id'
-  config.environment = :sandbox
-end
-
-# Check configuration
-puts Airwallex.configuration.api_url
-# => https://api-demo.airwallex.com/api/v1
-
-# Client is ready (authentication happens automatically on first request)
-client = Airwallex.client
-```
-
-## Files Created
-
-```text
-lib/airwallex.rb                       - Main module with configuration
-lib/airwallex/version.rb               - Version constant
-lib/airwallex/configuration.rb         - Configuration class
-lib/airwallex/client.rb                - HTTP client with Faraday
-lib/airwallex/errors.rb                - Exception hierarchy
-lib/airwallex/util.rb                  - Helper utilities
-lib/airwallex/webhook.rb               - Webhook verification
-lib/airwallex/middleware/idempotency.rb     - Auto request_id
-lib/airwallex/middleware/auth_refresh.rb    - Token management
-```
-
-## Key Features
-
-### Environment Safety
-- Defaults to `:sandbox` to prevent accidental production transactions
-- Validates environment selection
-- Dynamic URL generation
-
-### Authentication
-- Automatic Bearer token exchange
-- 30-minute token lifetime with 5-minute refresh buffer
-- Thread-safe token management
-- Transparent 401 retry
-
-### Idempotency
-- Automatic UUID v4 generation for `request_id`
-- Injected into request body (Airwallex specification)
-- Safe request retries
-
-### Error Handling
-- HTTP status mapped to specific exceptions
-- Polymorphic error body parsing
-- Detailed error information (`code`, `message`, `param`, `details`)
-
-### Webhook Security
-- HMAC-SHA256 signature verification
-- Replay attack protection (5-minute tolerance)
-- Constant-time comparison
-
-## What's Next
-
-**Iteration 2:** Testing Infrastructure
-- Set up RSpec, WebMock, VCR
-- Write comprehensive tests
-- Achieve 90%+ coverage
-
-**Sprint 2:** Resource Implementation
-- APIResource base class
-- Payment Intent resource
-- Transfer resource
-- Pagination system
-
-## Validation
-
-```bash
-# Check for errors
-bundle exec rubocop lib/
-# => 9 files inspected, no offenses detected ✅
-
-# Test gem loading
-bundle exec ruby -e "require './lib/airwallex'; puts 'OK'"
-# => OK ✅
-
-# Test configuration
-bundle exec ruby -e "
-  require './lib/airwallex'
-  Airwallex.configure { |c| c.api_key = 'test'; c.client_id = 'test' }
-  puts Airwallex.configuration.api_url
-"
-# => https://api-demo.airwallex.com/api/v1 ✅
-```
-
-## Time Spent
-
-Approximately 4 hours for:
-- Directory structure setup
-- Core class implementation
-- Faraday middleware
-- Rubocop configuration
-- Documentation
-
-## Notes
-
-- All code follows Ruby 3.1+ standards
-- No external API calls made yet (no tests)
-- Architecture matches research blueprints exactly
-- Ready for test implementation