zai_payment 1.0.2 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3356f8c1b0c4d7806f3d332dd18d4cd9faa2508a867d9bf75c100b80a8b47e4
-  data.tar.gz: cdf5dc1d7994ec2230d13ce989b489564d9cab6be4756f482e870898c91047e2
+  metadata.gz: a4b63d2fefc49eb419bc1de0db2cb41c3df25794f6efbf2b9a92ca6091112258
+  data.tar.gz: 1ba74f063b3360b79acafe36a25d43c0b92ae09bee3c5d3da2f3ef30bf4fa5ab
 SHA512:
-  metadata.gz: 7147ac27b27d63eac4c9ba4b51050ca539b4da4aa281a76a3bb569d3642ca691327194640ae0c950f5e7e31acf9f1a1fafb22cd80f27be879dd1a52efc39e2f3
-  data.tar.gz: bb2ce6f8c53a32ca8a84663aa00f028e7a6adcc9a166fe2137909ebdfff9ee69122bb6340460ac79ac5ff19dec777a8c3716b4afb1ff760d513f73bc232b2462
+  metadata.gz: 209ce54d8809117bb3fe6059c50dc1a6be4a7de974a961506936772b3f0480510b28382445ef113f4bf0ef914b314377bb3ddf5613ee942ad691be818e1d3383
+  data.tar.gz: e8efd4e2b0e5d2d42403d389c4218b95735ae4f1dcf60eb3e1e8012d23750bb2a0b8edd5fcc56f13816bc3c3de955de06f477230df5acce534824a15bebbc0ce

data/CHANGELOG.md

@@ -1,7 +1,87 @@
-## [Unreleased]
+## [Released]
+
+## [1.2.0] - 2025-10-22
+### Added
+- **Webhook Security: Signature Verification** 🔒
+  - `create_secret_key(secret_key:)` - Register a secret key with Zai
+  - `verify_signature(payload:, signature_header:, secret_key:, tolerance:)` - Verify webhook authenticity
+  - `generate_signature(payload, secret_key, timestamp)` - Utility for testing
+  - HMAC SHA256 signature verification with Base64 URL-safe encoding
+  - Timestamp validation to prevent replay attacks (configurable tolerance)
+  - Constant-time comparison to prevent timing attacks
+  - Support for multiple signatures (key rotation scenarios)
+
+### Documentation
+- **NEW**: [Authentication Guide](docs/AUTHENTICATION.md) - Comprehensive guide covering:
+  - Short way: `ZaiPayment.token` (one-liner approach)
+  - Long way: `TokenProvider.new(config:).bearer_token` (advanced control)
+  - Token lifecycle and automatic management
+  - Multiple configurations, testing, error handling
+  - Best practices and troubleshooting
+- **NEW**: [Webhook Security Quick Start](docs/WEBHOOK_SECURITY_QUICKSTART.md) - 5-minute setup guide
+- **NEW**: [Webhook Signature Implementation](docs/WEBHOOK_SIGNATURE.md) - Technical details
+- **NEW**: [Documentation Index](docs/README.md) - Central navigation for all docs
+- **Enhanced**: [Webhook Examples](examples/webhooks.md) - Added 400+ lines of examples:
+  - Complete Rails controller implementation
+  - Sinatra example
+  - Rack middleware example
+  - Background job processing pattern
+  - Idempotency pattern
+- **Enhanced**: [Webhook Technical Guide](docs/WEBHOOKS.md) - Added 170+ lines on security
+- **Reorganized**: All documentation moved to `docs/` folder for better organization
+- **Updated**: README.md - Now concise with clear links to detailed documentation
+
+### Testing
+- 56 new test cases for webhook signature verification
+- All tests passing: 95/95 ✓
+- Tests cover valid/invalid signatures, expired timestamps, malformed headers, edge cases
+
+### Security
+- ✅ OWASP compliance for webhook security
+- ✅ RFC 2104 (HMAC) implementation
+- ✅ RFC 4648 (Base64url) encoding
+- ✅ Protection against timing attacks, replay attacks, and MITM attacks
+
+**Full Changelog**: https://github.com/Sentia/zai-payment/compare/v1.1.0...v1.2.0
+
+## [1.1.0] - 2025-10-22
+### Added
+- **Webhooks API**: Full CRUD operations for managing Zai webhooks
+  - `ZaiPayment.webhooks.list` - List all webhooks with pagination
+  - `ZaiPayment.webhooks.show(id)` - Get a specific webhook
+  - `ZaiPayment.webhooks.create(...)` - Create a new webhook
+  - `ZaiPayment.webhooks.update(id, ...)` - Update an existing webhook
+  - `ZaiPayment.webhooks.delete(id)` - Delete a webhook
+- **Base API Client**: Reusable HTTP client for all API requests
+- **Response Wrapper**: Standardized response handling with error management
+- **Enhanced Error Handling**: New error classes for different API scenarios
+  - `ValidationError` (400, 422)
+  - `UnauthorizedError` (401)
+  - `ForbiddenError` (403)
+  - `NotFoundError` (404)
+  - `RateLimitError` (429)
+  - `ServerError` (5xx)
+  - `TimeoutError` and `ConnectionError` for network issues
+- Comprehensive test suite for webhook functionality
+- Example code in `examples/webhooks.rb`
+
+**Full Changelog**: https://github.com/Sentia/zai-payment/compare/v1.0.2...v1.1.0
+
+## [1.0.2] - 2025-10-22
+- Update gemspec files and readme
+
+**Full Changelog**: https://github.com/Sentia/zai-payment/releases/tag/v1.0.2
+
+
+##[1.0.1] - 2025-10-21
+- Update readme and versions
+
+**Full Changelog**: https://github.com/Sentia/zai-payment/releases/tag/v1.0.1
+
 
 ## [1.0.0] - 2025-10-21
 
 - Initial release: token auth client with in-memory caching (`ZaiPayment.token`, `refresh_token!`, `clear_token!`, `token_type`, `token_expiry`)
 
 **Full Changelog**: https://github.com/Sentia/zai-payment/commits/v1.0.0
+

data/IMPLEMENTATION.md

@@ -0,0 +1,201 @@
+# Implementation Summary: Zai Payment Webhooks
+
+## ✅ What Was Implemented
+
+### 1. Core Infrastructure (New Files)
+
+#### `/lib/zai_payment/client.rb`
+- Base HTTP client for all API requests
+- Handles authentication automatically
+- Supports GET, POST, PATCH, DELETE methods
+- Proper error handling and connection management
+- Thread-safe and reusable
+
+#### `/lib/zai_payment/response.rb`
+- Response wrapper class
+- Convenience methods: `success?`, `client_error?`, `server_error?`
+- Automatic error raising based on HTTP status
+- Clean data extraction from response body
+
+#### `/lib/zai_payment/resources/webhook.rb`
+- Complete CRUD operations for webhooks:
+  - `list(limit:, offset:)` - List all webhooks with pagination
+  - `show(webhook_id)` - Get specific webhook details
+  - `create(url:, object_type:, enabled:, description:)` - Create new webhook
+  - `update(webhook_id, ...)` - Update existing webhook
+  - `delete(webhook_id)` - Delete webhook
+- Full input validation
+- URL format validation
+- Comprehensive error messages
+
+### 2. Enhanced Error Handling
+
+#### `/lib/zai_payment/errors.rb` (Updated)
+Added new error classes:
+- `ApiError` - Base API error
+- `BadRequestError` (400)
+- `UnauthorizedError` (401)
+- `ForbiddenError` (403)
+- `NotFoundError` (404)
+- `ValidationError` (422)
+- `RateLimitError` (429)
+- `ServerError` (5xx)
+- `TimeoutError` - Network timeout
+- `ConnectionError` - Connection failed
+
+### 3. Main Module Integration
+
+#### `/lib/zai_payment.rb` (Updated)
+- Added `require` statements for new components
+- Added `webhooks` method that returns a singleton instance
+- Usage: `ZaiPayment.webhooks.list`
+
+### 4. Testing
+
+#### `/spec/zai_payment/resources/webhook_spec.rb` (New)
+Comprehensive test suite covering:
+- List webhooks (success, pagination, unauthorized)
+- Show webhook (success, not found, validation)
+- Create webhook (success, validation errors, API errors)
+- Update webhook (success, not found, validation)
+- Delete webhook (success, not found, validation)
+- Edge cases and error scenarios
+
+### 5. Documentation
+
+#### `/examples/webhooks.rb` (New)
+- Complete usage examples
+- All CRUD operations
+- Error handling patterns
+- Pagination examples
+- Custom client instances
+
+#### `/docs/WEBHOOKS.md` (New)
+- Architecture overview
+- API method documentation
+- Error handling guide
+- Best practices
+- Testing instructions
+- Future enhancements
+
+#### `/README.md` (Updated)
+- Added webhook usage section
+- Error handling examples
+- Updated roadmap (Webhooks: Done ✅)
+
+#### `/CHANGELOG.md` (Updated)
+- Added v1.1.0 release notes
+- Documented all new features
+- Listed all new error classes
+
+### 6. Version
+
+#### `/lib/zai_payment/version.rb` (Updated)
+- Bumped version to 1.1.0
+
+## 📁 File Structure
+
+```
+lib/
+├── zai_payment/
+│   ├── auth/                    # Authentication (existing)
+│   ├── client.rb                # ✨ NEW: Base HTTP client
+│   ├── response.rb              # ✨ NEW: Response wrapper
+│   ├── resources/
+│   │   └── webhook.rb           # ✨ NEW: Webhook CRUD operations
+│   ├── config.rb                # (existing)
+│   ├── errors.rb                # ✅ UPDATED: Added API error classes
+│   └── version.rb               # ✅ UPDATED: v1.1.0
+└── zai_payment.rb               # ✅ UPDATED: Added webhooks accessor
+
+spec/
+└── zai_payment/
+    └── resources/
+        └── webhook_spec.rb      # ✨ NEW: Comprehensive tests
+
+examples/
+└── webhooks.rb                  # ✨ NEW: Usage examples
+
+docs/
+└── WEBHOOKS.md                  # ✨ NEW: Complete documentation
+```
+
+## 🎯 Key Features
+
+1. **Clean API**: `ZaiPayment.webhooks.list`, `.show`, `.create`, `.update`, `.delete`
+2. **Automatic Authentication**: Uses existing TokenProvider
+3. **Comprehensive Validation**: URL format, required fields, etc.
+4. **Rich Error Handling**: Specific errors for each scenario
+5. **Pagination Support**: Built-in pagination for list operations
+6. **Thread-Safe**: Reuses existing thread-safe authentication
+7. **Well-Tested**: Full RSpec test coverage
+8. **Documented**: Inline docs, examples, and guides
+
+## 🚀 Usage
+
+```ruby
+# Configure once
+ZaiPayment.configure do |config|
+  config.environment = :prelive
+  config.client_id = ENV['ZAI_CLIENT_ID']
+  config.client_secret = ENV['ZAI_CLIENT_SECRET']
+  config.scope = ENV['ZAI_SCOPE']
+end
+
+# Use webhooks
+response = ZaiPayment.webhooks.list
+webhooks = response.data
+
+response = ZaiPayment.webhooks.create(
+  url: 'https://example.com/webhook',
+  object_type: 'transactions',
+  enabled: true
+)
+```
+
+## ✨ Best Practices Applied
+
+1. **Single Responsibility Principle**: Each class has one clear purpose
+2. **DRY**: Reusable Client and Response classes
+3. **Open/Closed**: Easy to extend for new resources (Users, Items, etc.)
+4. **Dependency Injection**: Client accepts custom config and token provider
+5. **Fail Fast**: Validation before API calls
+6. **Clear Error Messages**: Descriptive validation errors
+7. **RESTful Design**: Standard HTTP methods and status codes
+8. **Comprehensive Testing**: Unit tests for all scenarios
+9. **Documentation**: Examples, inline docs, and guides
+10. **Version Control**: Semantic versioning with changelog
+
+## 🔄 Ready for Extension
+
+The infrastructure is now in place to easily add more resources:
+
+```ruby
+# Future resources can follow the same pattern:
+lib/zai_payment/resources/
+├── webhook.rb       # ✅ Done
+├── user.rb          # Coming soon
+├── item.rb          # Coming soon
+├── transaction.rb   # Coming soon
+└── wallet.rb        # Coming soon
+```
+
+Each resource can reuse:
+- `ZaiPayment::Client` for HTTP requests
+- `ZaiPayment::Response` for response handling
+- Error classes for consistent error handling
+- Same authentication mechanism
+- Same configuration
+- Same testing patterns
+
+## 🎉 Summary
+
+Successfully implemented a complete, production-ready webhook management system for the Zai Payment gem with:
+- ✅ Full CRUD operations
+- ✅ Comprehensive testing
+- ✅ Rich error handling
+- ✅ Complete documentation
+- ✅ Clean, maintainable code
+- ✅ Following Ruby and Rails best practices
+- ✅ Ready for production use
+

data/README.md

@@ -44,27 +44,81 @@ ZaiPayment.configure do |c|
 end
 ```
 
-## 🚀 Authentication
+## 🚀 Quick Start
 
-The Zai Payment gem implements OAuth2 Client Credentials flow for secure authentication with the Zai API. The gem intelligently manages your authentication tokens behind the scenes, so you don't have to worry about token expiration or manual refreshes.
+### Authentication
 
-When you request a token, the gem automatically caches it and reuses it for subsequent requests. Since Zai tokens expire after 60 minutes, the gem monitors the token lifetime and seamlessly refreshes it before expiration — ensuring your API calls never fail due to stale credentials.
+Get an OAuth2 token with automatic caching and refresh:
 
-This automatic token management means you can focus on building your integration while the gem handles all the authentication complexity for you. Simply configure your credentials once, and the gem takes care of the rest.
+```ruby
+# Simple one-liner (recommended)
+token = ZaiPayment.token
+
+# Or with full control (advanced)
+config = ZaiPayment::Config.new
+config.environment = :prelive
+config.client_id = 'your_client_id'
+config.client_secret = 'your_client_secret'
+config.scope = 'your_scope'
+
+token_provider = ZaiPayment::Auth::TokenProvider.new(config: config)
+token = token_provider.bearer_token
+```
 
-For more details about Zai's OAuth2 authentication, see the [official documentation](https://developer.hellozai.com/reference/overview#authentication).
+The gem handles OAuth2 Client Credentials flow automatically - tokens are cached and refreshed before expiration.
 
-```ruby
-client = ZaiPayment::Auth::TokenProvider.new(config: ZaiPayment.config)
+📖 **[Complete Authentication Guide](docs/AUTHENTICATION.md)** - Two approaches, examples, and best practices
 
-client.bearer_token
+### Webhooks
+
+Manage webhook endpoints:
+
+```ruby
+# List webhooks
+response = ZaiPayment.webhooks.list
+webhooks = response.data
+
+# Create a webhook
+response = ZaiPayment.webhooks.create(
+  url: 'https://example.com/webhooks/zai',
+  object_type: 'transactions',
+  enabled: true
+)
+
+# Secure your webhooks with signature verification
+secret_key = SecureRandom.alphanumeric(32)
+ZaiPayment.webhooks.create_secret_key(secret_key: secret_key)
 ```
 
-Or, more easily, you can get a token with the convenience one-liner:
+**📚 Documentation:**
+- 📖 [Webhook Examples & Complete Guide](examples/webhooks.md) - Full CRUD operations and patterns
+- 🔒 [Security Quick Start](docs/WEBHOOK_SECURITY_QUICKSTART.md) - 5-minute webhook security setup
+- 🏗️ [Architecture & Implementation](docs/WEBHOOKS.md) - Detailed technical documentation
+- 🔐 [Signature Verification Details](docs/WEBHOOK_SIGNATURE.md) - Security implementation specs
 
+### Error Handling
+
+The gem provides specific error classes for different scenarios:
 
 ```ruby
-ZaiPayment.token
+begin
+  response = ZaiPayment.webhooks.create(
+    url: 'https://example.com/webhook',
+    object_type: 'transactions'
+  )
+rescue ZaiPayment::Errors::ValidationError => e
+  # Handle validation errors (400, 422)
+  puts "Validation error: #{e.message}"
+rescue ZaiPayment::Errors::UnauthorizedError => e
+  # Handle authentication errors (401)
+  puts "Authentication failed: #{e.message}"
+rescue ZaiPayment::Errors::NotFoundError => e
+  # Handle not found errors (404)
+  puts "Resource not found: #{e.message}"
+rescue ZaiPayment::Errors::ApiError => e
+  # Handle other API errors
+  puts "API error: #{e.message}"
+end
 ```
 
 ## 🧩 Roadmap
@@ -72,9 +126,9 @@ ZaiPayment.token
 | Area                            | Description                       | Status         |
 | ------------------------------- | --------------------------------- | -------------- |
 | ✅ Authentication                | OAuth2 Client Credentials flow    | Done           |
+| ✅ Webhooks                     | CRUD for webhook endpoints        | Done           |
 | 💳 Payments                     | Single and recurring payments     | 🚧 In progress |
 | 🏦 Virtual Accounts (VA / PIPU) | Manage virtual accounts & PayTo   | ⏳ Planned      |
-| 🧾 Webhooks                     | CRUD for webhook endpoints        | ⏳ Planned      |
 | 👤 Users                        | Manage PayIn / PayOut users       | ⏳ Planned      |
 | 💼 Wallets                      | Create and manage wallet accounts | ⏳ Planned      |
 
@@ -126,8 +180,22 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 Everyone interacting in the ZaiPayment project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/Sentia/zai-payment/blob/main/CODE_OF_CONDUCT.md).
 
-## 🔗 Resources
+## 📚 Documentation
+
+### Getting Started
+- [**Authentication Guide**](docs/AUTHENTICATION.md) - Two approaches to getting tokens, automatic management
+- [**Webhook Examples**](examples/webhooks.md) - Complete webhook usage guide
+- [**Documentation Index**](docs/README.md) - Full documentation navigation
+
+### Technical Guides
+- [Webhook Architecture](docs/WEBHOOKS.md) - Technical implementation details
+- [Architecture Overview](docs/ARCHITECTURE.md) - System architecture and design
+
+### Security
+- [Webhook Security Quick Start](docs/WEBHOOK_SECURITY_QUICKSTART.md) - 5-minute setup guide
+- [Signature Verification](docs/WEBHOOK_SIGNATURE.md) - Implementation details
 
+### External Resources
 - [Zai Developer Portal](https://developer.hellozai.com/)
 - [Zai API Reference](https://developer.hellozai.com/reference)
-- [AssemblyPay Auth Documentation](https://developer.hellozai.com/docs/introduction)
+- [Zai OAuth Documentation](https://developer.hellozai.com/docs/introduction)

data/docs/ARCHITECTURE.md

@@ -0,0 +1,232 @@
+# Zai Payment Webhook Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Client Application                        │
+└────────────────────────┬────────────────────────────────────────┘
+                         │
+                         │ ZaiPayment.webhooks.list()
+                         │ ZaiPayment.webhooks.create(...)
+                         │ ZaiPayment.webhooks.update(...)
+                         │ ZaiPayment.webhooks.delete(...)
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                     ZaiPayment (Module)                          │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │  config()       - Configuration singleton                 │  │
+│  │  auth()         - TokenProvider singleton                 │  │
+│  │  webhooks()     - Webhook resource singleton              │  │
+│  └───────────────────────────────────────────────────────────┘  │
+└────────────────────────┬────────────────────────────────────────┘
+                         │
+         ┌───────────────┴───────────────┐
+         │                               │
+         ▼                               ▼
+┌──────────────────┐          ┌──────────────────────┐
+│   Config         │          │  Auth::TokenProvider │
+│  ─────────────   │          │  ──────────────────  │
+│  - environment   │◄─────────│  Uses config         │
+│  - client_id     │          │  - bearer_token()    │
+│  - client_secret │          │  - refresh_token()   │
+│  - scope         │          │  - clear_token()     │
+│  - endpoints()   │          │                      │
+└──────────────────┘          └──────────────────────┘
+                                        │
+                                        │
+                                        ▼
+                              ┌──────────────────────┐
+                              │   TokenStore         │
+                              │  ──────────────────  │
+                              │  (MemoryStore)       │
+                              │  - fetch()           │
+                              │  - write()           │
+                              │  - clear()           │
+                              └──────────────────────┘
+         │
+         ▼
+┌─────────────────────────────────────────────────────────────────┐
+│              Resources::Webhook (Resource Layer)                 │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │  list(limit:, offset:)                                    │  │
+│  │  show(webhook_id)                                         │  │
+│  │  create(url:, object_type:, enabled:, description:)       │  │
+│  │  update(webhook_id, ...)                                  │  │
+│  │  delete(webhook_id)                                       │  │
+│  │                                                           │  │
+│  │  Private validation methods:                              │  │
+│  │  - validate_id!()                                         │  │
+│  │  - validate_presence!()                                   │  │
+│  │  - validate_url!()                                        │  │
+│  └───────────────────────────────────────────────────────────┘  │
+└────────────────────────┬────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Client (HTTP Layer)                           │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │  get(path, params:)                                       │  │
+│  │  post(path, body:)                                        │  │
+│  │  patch(path, body:)                                       │  │
+│  │  delete(path)                                             │  │
+│  │                                                           │  │
+│  │  Private:                                                 │  │
+│  │  - connection() - Faraday with auth headers              │  │
+│  │  - handle_faraday_error()                                │  │
+│  └───────────────────────────────────────────────────────────┘  │
+└────────────────────────┬────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      Faraday (HTTP Client)                       │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │  Authorization: Bearer <token>                            │  │
+│  │  Content-Type: application/json                           │  │
+│  │  Accept: application/json                                 │  │
+│  └───────────────────────────────────────────────────────────┘  │
+└────────────────────────┬────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                        Zai API                                   │
+│  sandbox.au-0000.api.assemblypay.com/webhooks                   │
+└────────────────────────┬────────────────────────────────────────┘
+                         │
+                         │ HTTP Response
+                         ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                   Response (Wrapper)                             │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │  status         - HTTP status code                        │  │
+│  │  body           - Raw response body                       │  │
+│  │  headers        - Response headers                        │  │
+│  │  data()         - Extracted data                          │  │
+│  │  meta()         - Pagination metadata                     │  │
+│  │  success?()     - 2xx status check                        │  │
+│  │  client_error?()- 4xx status check                        │  │
+│  │  server_error?()- 5xx status check                        │  │
+│  │                                                           │  │
+│  │  Private:                                                 │  │
+│  │  - check_for_errors!() - Raises specific errors          │  │
+│  └───────────────────────────────────────────────────────────┘  │
+└────────────────────────┬────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Error Hierarchy                               │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │  Error (Base)                                             │  │
+│  │    ├── AuthError                                          │  │
+│  │    ├── ConfigurationError                                 │  │
+│  │    ├── ApiError                                           │  │
+│  │    │     ├── BadRequestError (400)                        │  │
+│  │    │     ├── UnauthorizedError (401)                      │  │
+│  │    │     ├── ForbiddenError (403)                         │  │
+│  │    │     ├── NotFoundError (404)                          │  │
+│  │    │     ├── ValidationError (422)                        │  │
+│  │    │     ├── RateLimitError (429)                         │  │
+│  │    │     └── ServerError (5xx)                            │  │
+│  │    ├── TimeoutError                                       │  │
+│  │    └── ConnectionError                                    │  │
+│  └───────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Request Flow
+
+1. **Client calls** `ZaiPayment.webhooks.list()`
+2. **Module** returns singleton `Resources::Webhook` instance
+3. **Webhook resource** validates input and calls `client.get('/webhooks', params: {...})`
+4. **Client** prepares HTTP request with authentication
+5. **TokenProvider** provides valid bearer token (auto-refresh if expired)
+6. **Faraday** makes HTTP request to Zai API
+7. **Response** wraps Faraday response
+8. **Response** checks status and raises error if needed
+9. **Response** returns to client with `data()` and `meta()` methods
+10. **Client application** receives response and processes data
+
+## Key Design Decisions
+
+### 1. Singleton Pattern for Resources
+```ruby
+ZaiPayment.webhooks  # Always returns same instance
+```
+- Reduces object creation overhead
+- Consistent configuration across application
+- Easy to use in any context
+
+### 2. Dependency Injection
+```ruby
+Webhook.new(client: custom_client)
+```
+- Testable (can inject mock client)
+- Flexible (can use different configs)
+- Follows SOLID principles
+
+### 3. Response Wrapper
+```ruby
+response = webhooks.list
+response.success?  # Boolean check
+response.data      # Extracted data
+response.meta      # Pagination info
+```
+- Consistent interface across all resources
+- Rich API for checking status
+- Automatic error handling
+
+### 4. Fail Fast Validation
+```ruby
+validate_url!(url)  # Before API call
+```
+- Catches errors early
+- Better error messages
+- Reduces unnecessary API calls
+
+### 5. Resource-Based Organization
+```ruby
+lib/zai_payment/resources/
+  ├── webhook.rb
+  ├── user.rb      # Future
+  └── item.rb      # Future
+```
+- Easy to extend
+- Clear separation of concerns
+- Follows REST principles
+
+## Thread Safety
+
+- ✅ **TokenProvider**: Uses Mutex for thread-safe token refresh
+- ✅ **MemoryStore**: Thread-safe token storage
+- ✅ **Client**: Creates new Faraday connection per instance
+- ✅ **Webhook**: Stateless, no shared mutable state
+
+## Extension Points
+
+Add new resources by following the same pattern:
+
+```ruby
+# lib/zai_payment/resources/user.rb
+module ZaiPayment
+  module Resources
+    class User
+      def initialize(client: nil)
+        @client = client || Client.new
+      end
+      
+      def list
+        client.get('/users')
+      end
+      
+      def show(user_id)
+        client.get("/users/#{user_id}")
+      end
+    end
+  end
+end
+
+# lib/zai_payment.rb
+def users
+  @users ||= Resources::User.new
+end
+```
+