zai_payment 1.1.0 → 1.3.0

data/README.md

@@ -1,6 +1,15 @@
 # Zai Payment Ruby Library
 
+![GitHub License](https://img.shields.io/github/license/Sentia/zai-payment)
+[![Code of Conduct](https://img.shields.io/badge/code%20of%20conduct-MIT-blue.svg)](./CODE_OF_CONDUCT.md)
+[![Gem Version](https://badge.fury.io/rb/zai_payment.svg)](https://badge.fury.io/rb/zai_payment)
+[![GitHub release](https://img.shields.io/github/release/Sentia/zai-payment.svg)](https://github.com/Sentia/zai-payment/releases)
+[![Gem](https://img.shields.io/gem/dt/zai_payment.svg)](https://rubygems.org/gems/zai_payment)
 [![CI](https://github.com/Sentia/zai-payment/actions/workflows/ci.yml/badge.svg)](https://github.com/Sentia/zai-payment/actions/workflows/ci.yml)
+![Endpoint Badge](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FSentia%2Fzai-payment%2Fmain%2Fbadges%2Fcoverage.json)
+![GitHub top language](https://img.shields.io/github/languages/top/Sentia/zai-payment)
+[![Documentation](https://img.shields.io/badge/docs-rubydoc.info-blue.svg)](https://rubydoc.info/gems/zai_payment)
+[![Contributing](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](./CONTRIBUTING.md)
 
 A lightweight and extensible Ruby client for the **Zai (AssemblyPay)** API — starting with secure OAuth2 authentication, and ready for Payments, Virtual Accounts, Webhooks, and more.
 
@@ -8,22 +17,23 @@ A lightweight and extensible Ruby client for the **Zai (AssemblyPay)** API — s
 
 ## ✨ Features
 
-- 🔐 OAuth2 Client Credentials authentication with automatic token management  
-- 🧠 Smart token caching and refresh  
-- ⚙️ Environment-aware (Pre-live / Production)  
-- 🧱 Modular structure: easy to extend to Payments, Wallets, Webhooks, etc.  
-- 🧩 Thread-safe in-memory store (Redis support coming soon)  
-- 🧰 Simple Ruby API, no heavy dependencies  
+- 🔐 **OAuth2 Authentication** - Client Credentials flow with automatic token management  
+- 🧠 **Smart Token Caching** - Auto-refresh before expiration, thread-safe storage  
+- 👥 **User Management** - Create and manage payin (buyers) & payout (sellers) users  
+- 🪝 **Webhooks** - Full CRUD + secure signature verification (HMAC SHA256)  
+- ⚙️ **Environment-Aware** - Seamless Pre-live / Production switching  
+- 🧱 **Modular & Extensible** - Clean resource-based architecture  
+- 🧰 **Zero Heavy Dependencies** - Lightweight, fast, and reliable  
+- 📦 **Production Ready** - 88%+ test coverage, RuboCop compliant  
 
 ---
 
 ## 🧭 Installation
 
-### From GitHub (private repo)
 Add this line to your Gemfile:
 
 ```ruby
-gem 'zai_payment', '~> 1.0', '>= 1.0.2'
+gem 'zai_payment'
 ```
 
 Then install
@@ -44,67 +54,118 @@ 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
+```
+
+The gem handles OAuth2 Client Credentials flow automatically - tokens are cached and refreshed before expiration.
+
+📖 **[Complete Authentication Guide](docs/AUTHENTICATION.md)** - Two approaches, examples, and best practices
+
+### Users
 
-For more details about Zai's OAuth2 authentication, see the [official documentation](https://developer.hellozai.com/reference/overview#authentication).
+Manage payin (buyer) and payout (seller/merchant) users:
 
 ```ruby
-client = ZaiPayment::Auth::TokenProvider.new(config: ZaiPayment.config)
+# Create a payin user (buyer)
+response = ZaiPayment.users.create(
+  email: 'buyer@example.com',
+  first_name: 'John',
+  last_name: 'Doe',
+  country: 'USA',
+  mobile: '+1234567890'
+)
 
-client.bearer_token
-```
+# Create a payout user (seller/merchant)
+response = ZaiPayment.users.create(
+  email: 'seller@example.com',
+  first_name: 'Jane',
+  last_name: 'Smith',
+  country: 'AUS',
+  dob: '19900101',
+  address_line1: '456 Market St',
+  city: 'Sydney',
+  state: 'NSW',
+  zip: '2000'
+)
 
-Or, more easily, you can get a token with the convenience one-liner:
+# Create a business user with company details
+response = ZaiPayment.users.create(
+  email: 'director@company.com',
+  first_name: 'John',
+  last_name: 'Director',
+  country: 'AUS',
+  mobile: '+61412345678',
+  authorized_signer_title: 'Director',
+  company: {
+    name: 'My Company',
+    legal_name: 'My Company Pty Ltd',
+    tax_number: '123456789',
+    business_email: 'admin@company.com',
+    country: 'AUS',
+    charge_tax: true
+  }
+)
 
+# List users
+response = ZaiPayment.users.list(limit: 10, offset: 0)
 
-```ruby
-ZaiPayment.token
+# Get user details
+response = ZaiPayment.users.show('user_id')
+
+# Update user
+response = ZaiPayment.users.update('user_id', mobile: '+9876543210')
 ```
 
-## 🚀 Usage
+**📚 Documentation:**
+- 📖 [User Management Guide](docs/USERS.md) - Complete guide for payin and payout users
+- 💡 [User Examples](examples/users.md) - Real-world usage patterns and Rails integration
+- 🔗 [Zai: Onboarding a Payin User](https://developer.hellozai.com/docs/onboarding-a-payin-user)
+- 🔗 [Zai: Onboarding a Payout User](https://developer.hellozai.com/docs/onboarding-a-payout-user)
 
 ### Webhooks
 
-The gem provides a comprehensive interface for managing Zai webhooks:
+Manage webhook endpoints:
 
 ```ruby
-# List all webhooks
+# List 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'
+  enabled: true
 )
 
-# Delete a webhook
-response = ZaiPayment.webhooks.delete('webhook_id')
+# Secure your webhooks with signature verification
+secret_key = SecureRandom.alphanumeric(32)
+ZaiPayment.webhooks.create_secret_key(secret_key: secret_key)
 ```
 
-For more examples, see [examples/webhooks.md](examples/webhooks.md).
+**📚 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
 
@@ -137,9 +198,9 @@ end
 | ------------------------------- | --------------------------------- | -------------- |
 | ✅ Authentication                | OAuth2 Client Credentials flow    | Done           |
 | ✅ Webhooks                     | CRUD for webhook endpoints        | Done           |
+| ✅ Users                        | Manage PayIn / PayOut users       | Done           |
 | 💳 Payments                     | Single and recurring payments     | 🚧 In progress |
 | 🏦 Virtual Accounts (VA / PIPU) | Manage virtual accounts & PayTo   | ⏳ Planned      |
-| 👤 Users                        | Manage PayIn / PayOut users       | ⏳ Planned      |
 | 💼 Wallets                      | Create and manage wallet accounts | ⏳ Planned      |
 
 ## 🧪 Development
@@ -190,8 +251,27 @@ 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
+- [**User Management Guide**](docs/USERS.md) - Managing payin and payout users
+- [**Webhook Examples**](examples/webhooks.md) - Complete webhook usage guide
+- [**Documentation Index**](docs/README.md) - Full documentation navigation
+
+### Examples & Patterns
+- [User Examples](examples/users.md) - Real-world user management patterns
+- [Webhook Examples](examples/webhooks.md) - Webhook integration patterns
+
+### 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/badges/.gitkeep

@@ -0,0 +1,2 @@
+# This directory stores coverage badge JSON
+

data/badges/coverage.json

@@ -0,0 +1 @@
+{"schemaVersion": 1, "label": "coverage", "message": "95.18%", "color": "brightgreen"}