zai_payment 1.2.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4b63d2fefc49eb419bc1de0db2cb41c3df25794f6efbf2b9a92ca6091112258
-  data.tar.gz: 1ba74f063b3360b79acafe36a25d43c0b92ae09bee3c5d3da2f3ef30bf4fa5ab
+  metadata.gz: dabc0f9dc5f73ccb000c026d7a13eb171d14e447d0968af90458ddbc618ed415
+  data.tar.gz: a0152f5b7d19286f58d2c0cb0e7e551f657e3e3ddba54211ccb37fb145206674
 SHA512:
-  metadata.gz: 209ce54d8809117bb3fe6059c50dc1a6be4a7de974a961506936772b3f0480510b28382445ef113f4bf0ef914b314377bb3ddf5613ee942ad691be818e1d3383
-  data.tar.gz: e8efd4e2b0e5d2d42403d389c4218b95735ae4f1dcf60eb3e1e8012d23750bb2a0b8edd5fcc56f13816bc3c3de955de06f477230df5acce534824a15bebbc0ce
+  metadata.gz: eca4cb501d4135796dc7947eb21110ba1581672860450343995284f64209e200348791ade1573a599540702c82c86427f4fb5d3dcc7d4b3d91a1c775263fbd62
+  data.tar.gz: 45aabfa5d699dcb06c9e527ff72690698cdb70ab635d813070a94811f73b596bad47bde1771828eea1f200f6f2a1b805841cdc52677e69ef55994b0de9e5c96e

data/CHANGELOG.md

@@ -1,5 +1,76 @@
 ## [Released]
 
+## [1.3.1] - 2025-10-23
+### Changed
+- Update error response format
+- Update some docs
+
+**Full Changelog**: https://github.com/Sentia/zai-payment/compare/v1.3.0...v1.3.1
+
+## [1.3.0] - 2025-10-23
+### Added
+- **User Management API**: Full CRUD operations for managing Zai users (payin and payout) 👥
+  - `ZaiPayment.users.list(limit:, offset:)` - List all users with pagination
+  - `ZaiPayment.users.show(user_id)` - Get user details by ID
+  - `ZaiPayment.users.create(**attributes)` - Create payin (buyer) or payout (seller/merchant) users
+  - `ZaiPayment.users.update(user_id, **attributes)` - Update user information
+  - Support for both payin users (buyers) and payout users (sellers/merchants)
+  - Comprehensive validation for all user types
+  - Email format validation
+  - Country code validation (ISO 3166-1 alpha-3)
+  - Date of birth format validation (YYYYMMDD)
+  - User type validation (payin/payout)
+  - Progressive profile building support
+
+### Enhancements
+- **Client**: Added `base_endpoint` parameter to support multiple API endpoints
+  - Users API uses `core_base` endpoint
+  - Webhooks API continues to use `va_base` endpoint
+- **Response**: Updated `data` method to handle both `webhooks` and `users` response formats
+- **Main Module**: Added `users` accessor for convenient access to User resource
+
+### Documentation
+- **NEW**: [User Management Guide](docs/USERS.md) - Comprehensive guide covering:
+  - Overview of payin vs payout users
+  - Required fields for each user type
+  - Complete API reference with examples
+  - Field reference table
+  - Error handling patterns
+  - Best practices for each user type
+  - Response structures
+- **NEW**: [User Examples](examples/users.md) - 500+ lines of practical examples:
+  - Basic and advanced payin user creation
+  - Progressive profile building patterns
+  - Payout user creation (individual and company)
+  - International users (AU, UK, US)
+  - List, search, and pagination
+  - Update operations
+  - Rails integration examples
+  - Batch operations
+  - User profile validation helper
+  - RSpec integration tests
+  - Common patterns with retry logic
+- **NEW**: [User Quick Reference](docs/USER_QUICK_REFERENCE.md) - Quick lookup for common operations
+- **NEW**: [User Demo Script](examples/user_demo.rb) - Interactive demo of all user operations
+- **NEW**: [Implementation Summary](IMPLEMENTATION.md) - Detailed summary of the implementation
+- **Updated**: README.md - Added Users section with quick examples and updated roadmap
+
+### Testing
+- 40+ new test cases for User resource
+- All CRUD operations tested
+- Validation error handling tested
+- API error handling tested
+- Integration tests with main module
+- Tests for both payin and payout user types
+
+### API Endpoints
+- `GET /users` - List users
+- `GET /users/:id` - Show user
+- `POST /users` - Create user
+- `PATCH /users/:id` - Update user
+
+**Full Changelog**: https://github.com/Sentia/zai-payment/compare/v1.2.0...v1.3.0
+
 ## [1.2.0] - 2025-10-22
 ### Added
 - **Webhook Security: Signature Verification** 🔒

data/CONTRIBUTING.md

@@ -0,0 +1,383 @@
+# Contributing to Zai Payment
+
+First off, thank you for considering contributing to Zai Payment! 🎉 It's people like you that make this library better for everyone.
+
+## 📋 Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [How Can I Contribute?](#how-can-i-contribute)
+  - [Reporting Bugs](#reporting-bugs)
+  - [Suggesting Enhancements](#suggesting-enhancements)
+  - [Your First Code Contribution](#your-first-code-contribution)
+  - [Pull Requests](#pull-requests)
+- [Development Setup](#development-setup)
+- [Development Workflow](#development-workflow)
+- [Style Guidelines](#style-guidelines)
+  - [Git Commit Messages](#git-commit-messages)
+  - [Ruby Style Guide](#ruby-style-guide)
+  - [Documentation](#documentation)
+- [Testing](#testing)
+- [Community](#community)
+
+---
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [contact@sentia.com.au](mailto:contact@sentia.com.au).
+
+---
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+Before creating bug reports, please check the [existing issues](https://github.com/Sentia/zai-payment/issues) as you might find that you don't need to create one. When you are creating a bug report, please include as many details as possible:
+
+**Before Submitting A Bug Report:**
+- Check the [documentation](https://rubydoc.info/gems/zai_payment) to confirm your understanding of the expected behavior
+- Check if the issue has already been reported
+- Perform a cursory search to see if the problem has been discussed or resolved
+
+**How to Submit A Good Bug Report:**
+
+Bugs are tracked as [GitHub issues](https://github.com/Sentia/zai-payment/issues). Create an issue and provide the following information:
+
+- **Use a clear and descriptive title** for the issue to identify the problem
+- **Describe the exact steps to reproduce the problem** in as much detail as possible
+- **Provide specific examples** to demonstrate the steps (include code snippets)
+- **Describe the behavior you observed** after following the steps
+- **Explain which behavior you expected to see instead** and why
+- **Include details about your environment**:
+  - Ruby version (`ruby -v`)
+  - Gem version (`bundle list | grep zai_payment`)
+  - OS and version
+
+### Suggesting Enhancements
+
+Enhancement suggestions are tracked as [GitHub issues](https://github.com/Sentia/zai-payment/issues). When creating an enhancement suggestion, please include:
+
+- **Use a clear and descriptive title**
+- **Provide a detailed description** of the suggested enhancement
+- **Provide specific examples** to demonstrate the use case
+- **Describe the current behavior** and **explain the desired behavior**
+- **Explain why this enhancement would be useful** to most users
+- **List any similar features** in other libraries that inspired the suggestion
+
+### Your First Code Contribution
+
+Unsure where to begin contributing? You can start by looking through these issues:
+
+- **Good First Issue** - issues that should only require a few lines of code
+- **Help Wanted** - issues that may be more involved
+
+### Pull Requests
+
+Please follow these steps to have your contribution considered by the maintainers:
+
+1. **Fork the repository** and create your branch from `main`
+2. **Make your changes** following our [style guidelines](#style-guidelines)
+3. **Add or update tests** as needed
+4. **Ensure the test suite passes** (`bundle exec rspec`)
+5. **Run the linter** and fix any issues (`bundle exec rubocop`)
+6. **Update the documentation** if you've changed APIs or added features
+7. **Write clear commit messages** following our [commit message guidelines](#git-commit-messages)
+8. **Open a pull request** with a clear title and description
+
+**Pull Request Guidelines:**
+- Keep changes focused - one feature/fix per PR
+- Link any relevant issues in the PR description
+- Update CHANGELOG.md if appropriate
+- Maintain backward compatibility when possible
+- Include tests for new functionality
+- Follow the existing code style
+
+---
+
+## Development Setup
+
+### Prerequisites
+
+- **Ruby** 3.0 or higher
+- **Bundler** 2.0 or higher
+- **Git**
+
+### Getting Started
+
+1. **Fork and clone the repository:**
+
+```bash
+git clone git@github.com:Sentia/zai-payment.git
+cd zai-payment
+```
+
+2. **Install dependencies:**
+
+```bash
+bin/setup
+```
+
+This will:
+- Install all required gems
+- Set up git hooks (if applicable)
+- Prepare your development environment
+
+3. **Verify your setup:**
+
+```bash
+bundle exec rspec
+bundle exec rubocop
+```
+
+All tests should pass and there should be no linting errors.
+
+### Interactive Console
+
+For quick testing and experimentation:
+
+```bash
+bin/console
+```
+
+This launches an IRB session with the gem loaded and ready to use.
+
+---
+
+## Development Workflow
+
+### Branch Naming
+
+Use descriptive branch names that reflect the work being done:
+
+- `feature/description` - for new features
+- `bugfix/description` - for bug fixes
+- `docs/description` - for documentation changes
+- `refactor/description` - for code refactoring
+- `test/description` - for test improvements
+
+Examples:
+- `feature/add-payment-resource`
+- `bugfix/fix-token-refresh`
+- `docs/improve-webhook-examples`
+
+### Making Changes
+
+1. **Create a feature branch:**
+
+```bash
+git checkout -b feature/my-new-feature
+```
+
+2. **Make your changes** following our style guidelines
+
+3. **Write or update tests:**
+
+```bash
+bundle exec rspec
+```
+
+4. **Check code quality:**
+
+```bash
+bundle exec rubocop
+# Auto-fix issues when possible
+bundle exec rubocop -a
+```
+
+5. **Commit your changes:**
+
+```bash
+git add .
+git commit -m "feat: add awesome new feature"
+```
+
+6. **Push to your fork:**
+
+```bash
+git push origin feature/my-new-feature
+```
+
+7. **Open a Pull Request** on GitHub
+
+---
+
+## Style Guidelines
+
+### Git Commit Messages
+
+We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+
+**Format:**
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Types:**
+- `feat:` - A new feature
+- `fix:` - A bug fix
+- `docs:` - Documentation only changes
+- `style:` - Changes that don't affect code meaning (whitespace, formatting)
+- `refactor:` - Code change that neither fixes a bug nor adds a feature
+- `perf:` - Performance improvements
+- `test:` - Adding or updating tests
+- `chore:` - Changes to build process or auxiliary tools
+
+**Examples:**
+```
+feat(webhooks): add support for webhook signature verification
+
+fix(auth): prevent token refresh race condition
+
+docs: update README with webhook examples
+
+test(client): add specs for error handling
+```
+
+**Guidelines:**
+- Use present tense ("add feature" not "added feature")
+- Use imperative mood ("move cursor to..." not "moves cursor to...")
+- First line should be 50 characters or less
+- Reference issues and pull requests after the first line
+
+### Ruby Style Guide
+
+This project follows the [Ruby Style Guide](https://rubystyle.guide/) and uses [RuboCop](https://github.com/rubocop/rubocop) for enforcement.
+
+**Key principles:**
+- Use 2 spaces for indentation (no tabs)
+- Keep line length to 120 characters or less
+- Use `snake_case` for methods and variables
+- Use `CamelCase` for classes and modules
+- Write clear, self-documenting code
+- Add comments for complex logic
+- Follow existing patterns in the codebase
+
+**Run RuboCop:**
+```bash
+# Check for issues
+bundle exec rubocop
+
+# Auto-fix issues when possible
+bundle exec rubocop -a
+```
+
+### Documentation
+
+- **Public APIs must be documented** using YARD syntax
+- **Include examples** in documentation when helpful
+- **Update README.md** when adding new features
+- **Update relevant docs/** files for architectural changes
+- **Keep CHANGELOG.md** updated with notable changes
+
+**YARD Documentation Example:**
+```ruby
+# Fetches a webhook by its ID
+#
+# @param id [String] the webhook ID
+# @return [ZaiPayment::Response] the response containing webhook data
+# @raise [ZaiPayment::Errors::NotFoundError] if webhook doesn't exist
+#
+# @example
+#   response = client.webhooks.get('wh_123')
+#   webhook = response.data
+#
+def get(id)
+  # implementation
+end
+```
+
+---
+
+## Testing
+
+This project uses [RSpec](https://rspec.info/) for testing.
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/zai_payment/client_spec.rb
+
+# Run specific test
+bundle exec rspec spec/zai_payment/client_spec.rb:10
+
+# Run with coverage report
+bundle exec rspec --format documentation
+```
+
+### Writing Tests
+
+- **Write tests for all new features and bug fixes**
+- **Use descriptive test names** that explain what is being tested
+- **Follow the Arrange-Act-Assert pattern**
+- **Use factories or fixtures** for test data
+- **Mock external API calls** using VCR or WebMock
+- **Aim for high test coverage** (we target 90%+ coverage)
+
+**Test Example:**
+```ruby
+RSpec.describe ZaiPayment::Client do
+  describe '#initialize' do
+    context 'with valid configuration' do
+      it 'creates a client instance' do
+        config = ZaiPayment::Config.new
+        client = described_class.new(config: config)
+        
+        expect(client).to be_a(described_class)
+      end
+    end
+
+    context 'without configuration' do
+      it 'uses default configuration' do
+        client = described_class.new
+        
+        expect(client.config).to be_a(ZaiPayment::Config)
+      end
+    end
+  end
+end
+```
+
+### Test Coverage
+
+- Coverage reports are generated automatically with SimpleCov
+- View coverage reports in `coverage/index.html`
+- New code should maintain or improve overall coverage
+- Don't write tests just to increase coverage - write meaningful tests
+
+---
+
+## Community
+
+### Questions?
+
+- **GitHub Discussions** - For general questions and discussions
+- **GitHub Issues** - For bugs and feature requests
+- **Email** - [contact@sentia.com.au](mailto:contact@sentia.com.au)
+
+### Recognition
+
+Contributors will be recognized in:
+- The project's README (if significant contribution)
+- The CHANGELOG for their specific contributions
+- Release notes
+
+### Need Help?
+
+Don't hesitate to ask questions! We're here to help:
+- Comment on an issue you'd like to work on
+- Open a discussion for clarification
+- Reach out via email
+
+---
+
+## Thank You! 🙏
+
+Your contributions to open source, large or small, make projects like this possible. Thank you for taking the time to contribute!
+