airwallex 0.2.0 → 0.3.0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: airwallex
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Chayut Orapinpatipat
@@ -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

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

data/docs/internal/20251125_iteration_1_summary.md

@@ -1,342 +0,0 @@
-# Sprint 1 - Iteration 1 Summary
-
-**Date:** 25 November 2025  
-**Status:** Core Architecture Complete  
-**Rubocop:** ✅ No offenses
-
-## Completed Work
-
-### 1. Gem Directory Structure ✅
-
-Created the complete directory structure as per architectural blueprint:
-
-```text
-lib/airwallex/
-├── api_operations/     (ready for Sprint 2)
-├── resources/          (ready for Sprint 2)
-├── middleware/
-│   ├── idempotency.rb
-│   └── auth_refresh.rb
-├── errors.rb
-├── client.rb
-├── configuration.rb
-├── util.rb
-├── webhook.rb
-└── version.rb
-```
-
-**Files Created:**
-- 9 Ruby files
-- 3 directories
-- All files pass Rubocop validation
-
-### 2. Configuration Management ✅
-
-Implemented `Airwallex::Configuration` class with:
-
-**Features:**
-- Environment selection (`:sandbox`, `:production`)
-- Dynamic URL generation for API and Files endpoints
-- Safe defaults (sandbox as default environment)
-- Credential validation with detailed error messages
-- API version pinning (default: `2024-09-27`)
-- Logger configuration support
-
-**Key Methods:**
-- `#api_url` - Returns environment-specific API base URL
-- `#files_url` - Returns environment-specific files URL
-- `#validate!` - Validates configuration before use
-- `#configured?` - Checks if minimum configuration is present
-- `#environment=` - Validates and sets environment with type checking
-
-**URLs:**
-- Sandbox API: `https://api-demo.airwallex.com/api/v1`
-- Production API: `https://api.airwallex.com/api/v1`
-- Sandbox Files: `https://files-demo.airwallex.com`
-- Production Files: `https://files.airwallex.com`
-
-### 3. HTTP Transport Layer ✅
-
-Implemented `Airwallex::Client` class using Faraday with:
-
-**Middleware Stack:**
-1. JSON request encoding
-2. Multipart support (for file uploads)
-3. Retry logic with exponential backoff
-4. JSON response parsing
-5. Logging (when logger configured)
-
-**Headers Automatically Injected:**
-- `Content-Type: application/json`
-- `User-Agent: Airwallex-Ruby/{version} Ruby/{ruby_version}`
-- `x-api-version: 2024-09-27`
-- `Authorization: Bearer {token}` (after authentication)
-
-**Retry Configuration:**
-- Max retries: 3
-- Initial interval: 0.5s
-- Backoff factor: 2x
-- Jitter: 50% randomness
-- Safe methods: GET, DELETE
-- Retry statuses: 429, 500, 502, 503, 504
-
-**HTTP Methods:**
-- `#get(path, params, headers)`
-- `#post(path, body, headers)`
-- `#put(path, body, headers)`
-- `#patch(path, body, headers)`
-- `#delete(path, params, headers)`
-
-### 4. Authentication System ✅
-
-Implemented Bearer token authentication with:
-
-**Token Exchange:**
-- Endpoint: `POST /api/v1/authentication/login`
-- Headers: `x-client-id`, `x-api-key`
-- Response: JWT token with 30-minute expiration
-
-**Token Lifecycle:**
-- Automatic tracking of token expiration
-- Proactive refresh (5-minute buffer before expiration)
-- Thread-safe token management (Mutex protection)
-- Transparent re-authentication on 401 errors
-
-**Key Methods:**
-- `#authenticate!` - Exchanges credentials for access token
-- `#token_expired?` - Checks if token needs refresh
-- `#ensure_authenticated!` - Ensures valid token before request
-
-### 5. Token Refresh Middleware ✅
-
-Implemented `Airwallex::Middleware::AuthRefresh` with:
-
-**Features:**
-- Automatic token validation before each request
-- Intercepts 401 Unauthorized responses
-- One automatic retry after token refresh
-- Skips authentication for login endpoint itself
-- Prevents infinite retry loops
-
-**Behavior:**
-1. Check token validity before request
-2. Refresh if expired (proactive)
-3. If 401 response, refresh and retry once
-4. Update Authorization header with new token
-
-### 6. Error Handling Framework ✅
-
-Implemented comprehensive error system with:
-
-**Exception Hierarchy:**
-```ruby
-Airwallex::Error (base)
-├── Airwallex::ConfigurationError
-├── Airwallex::BadRequestError (400)
-├── Airwallex::AuthenticationError (401)
-├── Airwallex::PermissionError (403)
-│   └── Airwallex::SCARequiredError
-├── Airwallex::NotFoundError (404)
-├── Airwallex::RateLimitError (429)
-├── Airwallex::APIError (500+)
-├── Airwallex::InsufficientFundsError
-└── Airwallex::SignatureVerificationError
-```
-
-**Error Attributes:**
-- `code` - API error code (e.g., `insufficient_fund`)
-- `message` - Human-readable error message
-- `param` - Field that caused the error (from `source`)
-- `details` - Additional error details array
-- `http_status` - HTTP status code
-
-**Polymorphic Error Parsing:**
-Handles all three API error formats:
-1. Simple: `{ code, message, source }`
-2. Complex: `{ code, message, details[] }`
-3. Nested: `{ code, message, source: "nested.path" }`
-
-### 7. Idempotency Middleware ✅
-
-Implemented `Airwallex::Middleware::Idempotency` with:
-
-**Features:**
-- Automatic UUID v4 generation for `request_id`
-- Injection into request body (not headers, as per Airwallex spec)
-- Preserves user-provided `request_id` for reconciliation
-- Only applies to POST, PUT, PATCH methods
-
-**Behavior:**
-```ruby
-# Without request_id
-{ amount: 100 } → { amount: 100, request_id: "uuid-v4" }
-
-# With request_id (preserved)
-{ amount: 100, request_id: "my-id" } → { amount: 100, request_id: "my-id" }
-```
-
-**Safety:**
-- Prevents duplicate financial transactions
-- Enables safe request retries
-- Supports reconciliation with internal systems
-
-### 8. Utility Modules ✅
-
-Implemented `Airwallex::Util` with helpers for:
-
-**Date/Time Formatting:**
-- `#format_date_time` - Converts Ruby Date/Time to ISO 8601
-- `#parse_date_time` - Parses ISO 8601 strings to Time objects
-- Automatic timezone conversion to UTC
-
-**Data Manipulation:**
-- `#symbolize_keys` - Convert hash keys to symbols
-- `#deep_symbolize_keys` - Recursive symbol conversion
-- `#to_money` - Convert values to BigDecimal for precision
-
-**Idempotency:**
-- `#generate_idempotency_key` - Creates UUID v4 for request_id
-
-### 9. Webhook Verification ✅
-
-Implemented `Airwallex::Webhook` module with:
-
-**Signature Verification:**
-- Algorithm: HMAC-SHA256
-- Data: `timestamp + payload`
-- Constant-time comparison (timing attack prevention)
-
-**Replay Protection:**
-- Timestamp tolerance: 300 seconds (5 minutes, configurable)
-- Rejects old/replayed webhooks
-
-**Event Construction:**
-- `Event` object with `id`, `type`, `data`, `created_at`
-- JSON parsing with error handling
-- Immutable event objects
-
-**Key Methods:**
-- `#construct_event` - Full verification and parsing
-- `#verify_signature` - HMAC validation
-- `#compute_signature` - Signature generation
-- `#verify_timestamp` - Replay protection
-
-### 10. Main Module Integration ✅
-
-Updated `lib/airwallex.rb` with:
-
-**Configuration Block:**
-```ruby
-Airwallex.configure do |config|
-  config.api_key = "key"
-  config.client_id = "id"
-  config.environment = :sandbox
-end
-```
-
-**Module Methods:**
-- `Airwallex.configuration` - Access current configuration
-- `Airwallex.configure { }` - Configure the gem
-- `Airwallex.client` - Get singleton client instance
-- `Airwallex.reset!` - Reset configuration and client
-
-### 11. Code Quality ✅
-
-**Rubocop Configuration:**
-- Disabled overly strict cops for financial software
-- Increased method length limits (15 lines)
-- Increased ABC size limits (25)
-- Disabled documentation requirement (will add later)
-- Allowed short parameter names (a, b for comparison)
-
-**Current Status:**
-- ✅ 9 files inspected
-- ✅ 0 offenses detected
-- ✅ All code follows style guide
-- ✅ No syntax errors
-- ✅ All requires working
-
-## Technical Decisions
-
-### 1. Idempotency in Body vs Header
-
-**Decision:** Inject `request_id` in request body  
-**Rationale:** Airwallex API specification requires it in body, unlike Stripe which uses headers  
-**Impact:** Custom middleware required instead of standard Faraday middleware
-
-### 2. Sandbox as Default Environment
-
-**Decision:** Default to `:sandbox` environment  
-**Rationale:** Safety - prevents accidental real-money transactions  
-**Impact:** Users must explicitly opt-in to production
-
-### 3. Token Refresh Buffer
-
-**Decision:** Refresh tokens 5 minutes before expiration  
-**Rationale:** Prevents mid-request expiration in long-running operations  
-**Impact:** Slightly more authentication calls, but better reliability
-
-### 4. Thread-Safe Token Management
-
-**Decision:** Use Mutex for token refresh  
-**Rationale:** Prevent race conditions in multi-threaded environments  
-**Impact:** Small performance cost, but ensures correctness
-
-### 5. Retry Logic Separation
-
-**Decision:** Separate retry logic in Faraday middleware, not in idempotency middleware  
-**Rationale:** Clear separation of concerns, easier to test  
-**Impact:** Two middleware components instead of one
-
-## Known Limitations
-
-1. **No Resource Classes Yet** - Only infrastructure, no domain objects (Sprint 2)
-2. **No Pagination** - AutoPaginator not implemented (Sprint 2)
-3. **No OAuth Support** - Only Bearer token (Sprint 2+)
-4. **No SCA Handling** - Strong Customer Authentication deferred (Sprint 2+)
-5. **No Tests Yet** - Test infrastructure is next task
-
-## Next Steps
-
-### Immediate (Iteration 2)
-
-1. Set up RSpec, WebMock, VCR
-2. Create test fixtures for API responses
-3. Write tests for Configuration class
-4. Write tests for Client authentication flow
-5. Write tests for Error parsing (all formats)
-6. Write tests for Idempotency middleware
-7. Write tests for AuthRefresh middleware
-8. Achieve 90%+ code coverage
-
-### Sprint 2 Preview
-
-1. Implement APIResource base class
-2. Create API operations mixins (Create, Retrieve, List)
-3. Build pagination system (cursor and offset)
-4. Implement first resources:
-   - PaymentIntent
-   - Transfer
-   - Beneficiary
-5. Add OAuth support for Platform accounts
-
-## Metrics
-
-- **Files Created:** 9
-- **Lines of Code:** ~500
-- **Rubocop Offenses:** 0
-- **Test Coverage:** 0% (tests next iteration)
-- **Dependencies Added:** 3 runtime, 3 development
-- **Time Spent:** ~4 hours
-
-## Risks Mitigated
-
-1. ✅ Token refresh race conditions - Mutex locks implemented
-2. ✅ Request duplication - Automatic idempotency keys
-3. ✅ Accidental production usage - Sandbox default
-4. ✅ Webhook replay attacks - Timestamp validation
-5. ✅ Timing attacks on signatures - Constant-time comparison
-
-## Open Questions
-
-None - architecture is solid and ready for testing.