zai_payment 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 719c0663d33f0ced4d8bcc6627dd58ce98b8c14f436d9ce02210f01fc04b99d3
-  data.tar.gz: 85e8ae991cec90cd59e11f8234cdff9a7f684d4c5632bd9fd4659dc1af4ccedf
+  metadata.gz: e3dde823881d82243bdd2f57882c57cfe06ba21d20ab5402b58a876c7c752e8c
+  data.tar.gz: 37ce743767afba2f834354a81102cc445c544151c26601e59a0f82eb6b967a92
 SHA512:
-  metadata.gz: 1536177552b6ba2e10bb61734f574e697275cba87c74af530bbf8c125f37927f1cb2bf5de7dc4b94dffaaccd563f4d9f49ab96d1d40bf6fc5511f1ddf51adf11
-  data.tar.gz: 843f7c8d8650fc974af5a701d33e139cc1170a84cf064d765bc31729a0c3cd95487e4e51d4c06595a2e70bcc3f104a908d39c00343acc89d9054d146c7f31d9a
+  metadata.gz: 0b96c6511bc25c2dcbfe44af58957b160c3bd7ac1fb6aa94fb5708ced6a6e2ff6a209f188f664eb6c857ebe4177f5260191eb62aa1e64924adc57d695815ed38
+  data.tar.gz: 6e2410984fe931c17097f145de9a23e7c6048af308c068e7f590efab9991a21c838aed6158bb1be56863fa9e86090f46599eaffec1cf415e2610c46861de06e1

data/CHANGELOG.md

@@ -1,7 +1,43 @@
-## [Unreleased]
+## [Released]
+
+## [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

@@ -23,9 +23,7 @@ A lightweight and extensible Ruby client for the **Zai (AssemblyPay)** API — s
 Add this line to your Gemfile:
 
 ```ruby
-gem "zai_payment",
-    git: "https://github.com/Sentia/zai-payment.git",
-    branch: "main"
+gem 'zai_payment', '~> 1.0', '>= 1.0.2'
 ```
 
 Then install
@@ -69,14 +67,78 @@ Or, more easily, you can get a token with the convenience one-liner:
 ZaiPayment.token
 ```
 
+## 🚀 Usage
+
+### Webhooks
+
+The gem provides a comprehensive interface for managing Zai webhooks:
+
+```ruby
+# List all webhooks
+response = ZaiPayment.webhooks.list
+webhooks = response.data
+
+# List with pagination
+response = ZaiPayment.webhooks.list(limit: 20, offset: 10)
+
+# Get a specific webhook
+response = ZaiPayment.webhooks.show('webhook_id')
+webhook = response.data
+
+# Create a webhook
+response = ZaiPayment.webhooks.create(
+  url: 'https://example.com/webhooks/zai',
+  object_type: 'transactions',
+  enabled: true,
+  description: 'Production webhook for transactions'
+)
+
+# Update a webhook
+response = ZaiPayment.webhooks.update(
+  'webhook_id',
+  enabled: false,
+  description: 'Temporarily disabled'
+)
+
+# Delete a webhook
+response = ZaiPayment.webhooks.delete('webhook_id')
+```
+
+For more examples, see [examples/webhooks.md](examples/webhooks.md).
+
+### Error Handling
+
+The gem provides specific error classes for different scenarios:
+
+```ruby
+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
 
 | 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      |
 

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
+```
+