zai_payment 1.0.1 → 1.1.0

data/docs/WEBHOOKS.md

@@ -0,0 +1,157 @@
+# Zai Payment Webhook Implementation
+
+## Overview
+This document provides a summary of the webhook implementation in the zai_payment gem.
+
+## Architecture
+
+### Core Components
+
+1. **Client** (`lib/zai_payment/client.rb`)
+   - Base HTTP client for making API requests
+   - Handles authentication automatically via TokenProvider
+   - Supports GET, POST, PATCH, DELETE methods
+   - Manages connection with proper headers and JSON encoding/decoding
+
+2. **Response** (`lib/zai_payment/response.rb`)
+   - Wraps Faraday responses
+   - Provides convenient methods: `success?`, `client_error?`, `server_error?`
+   - Automatically raises appropriate errors based on HTTP status
+   - Extracts data and metadata from response body
+
+3. **Webhook Resource** (`lib/zai_payment/resources/webhook.rb`)
+   - Implements all CRUD operations for webhooks
+   - Full input validation
+   - Clean, documented API
+
+4. **Enhanced Error Handling** (`lib/zai_payment/errors.rb`)
+   - Specific error classes for different scenarios
+   - Makes debugging and error handling easier
+
+## API Methods
+
+### List Webhooks
+```ruby
+ZaiPayment.webhooks.list(limit: 10, offset: 0)
+```
+- Returns paginated list of webhooks
+- Response includes `data` (array of webhooks) and `meta` (pagination info)
+
+### Show Webhook
+```ruby
+ZaiPayment.webhooks.show(webhook_id)
+```
+- Returns details of a specific webhook
+- Raises `NotFoundError` if webhook doesn't exist
+
+### Create Webhook
+```ruby
+ZaiPayment.webhooks.create(
+  url: 'https://example.com/webhook',
+  object_type: 'transactions',
+  enabled: true,
+  description: 'Optional description'
+)
+```
+- Validates URL format
+- Validates required fields
+- Returns created webhook with ID
+
+### Update Webhook
+```ruby
+ZaiPayment.webhooks.update(
+  webhook_id,
+  url: 'https://example.com/new-webhook',
+  enabled: false
+)
+```
+- All fields are optional
+- Only updates provided fields
+- Validates URL format if URL is provided
+
+### Delete Webhook
+```ruby
+ZaiPayment.webhooks.delete(webhook_id)
+```
+- Permanently deletes the webhook
+- Returns 204 No Content on success
+
+## Error Handling
+
+The gem provides specific error classes:
+
+| Error Class | HTTP Status | Description |
+|------------|-------------|-------------|
+| `ValidationError` | 400, 422 | Invalid input data |
+| `UnauthorizedError` | 401 | Authentication failed |
+| `ForbiddenError` | 403 | Access denied |
+| `NotFoundError` | 404 | Resource not found |
+| `RateLimitError` | 429 | Too many requests |
+| `ServerError` | 5xx | Server-side error |
+| `TimeoutError` | - | Request timeout |
+| `ConnectionError` | - | Connection failed |
+
+Example:
+```ruby
+begin
+  response = ZaiPayment.webhooks.create(...)
+rescue ZaiPayment::Errors::ValidationError => e
+  puts "Validation failed: #{e.message}"
+rescue ZaiPayment::Errors::UnauthorizedError => e
+  puts "Authentication failed: #{e.message}"
+end
+```
+
+## Best Practices Implemented
+
+1. **Single Responsibility**: Each class has a clear, focused purpose
+2. **DRY (Don't Repeat Yourself)**: Client and Response classes are reusable
+3. **Error Handling**: Comprehensive error handling with specific error classes
+4. **Input Validation**: All inputs are validated before making API calls
+5. **Documentation**: Inline documentation with examples
+6. **Testing**: Comprehensive test coverage using RSpec
+7. **Thread Safety**: TokenProvider uses mutex for thread-safe token refresh
+8. **Configuration**: Centralized configuration management
+9. **RESTful Design**: Follows REST principles for resource management
+10. **Response Wrapping**: Consistent response format across all methods
+
+## Usage Examples
+
+See `examples/webhooks.rb` for complete examples including:
+- Basic CRUD operations
+- Pagination
+- Error handling
+- Custom client instances
+
+## Testing
+
+Run the webhook tests:
+```bash
+bundle exec rspec spec/zai_payment/resources/webhook_spec.rb
+```
+
+The test suite covers:
+- All CRUD operations
+- Success and error scenarios
+- Input validation
+- Error handling
+- Edge cases
+
+## Future Enhancements
+
+Potential improvements for future versions:
+1. Webhook job management (list jobs, show job details)
+2. Webhook signature verification
+3. Webhook retry logic
+4. Bulk operations
+5. Async webhook operations
+
+## API Reference
+
+For the official Zai API documentation, see:
+- [List Webhooks](https://developer.hellozai.com/reference/getallwebhooks)
+- [Show Webhook](https://developer.hellozai.com/reference/getwebhookbyid)
+- [Create Webhook](https://developer.hellozai.com/reference/createwebhook)
+- [Update Webhook](https://developer.hellozai.com/reference/updatewebhook)
+- [Delete Webhook](https://developer.hellozai.com/reference/deletewebhookbyid)
+

data/examples/webhooks.md

@@ -0,0 +1,146 @@
+# Webhook Examples
+
+This file demonstrates how to use the ZaiPayment webhook functionality.
+
+## Setup
+
+```ruby
+require 'zai_payment'
+
+# Configure the gem
+ZaiPayment.configure do |config|
+  config.environment = :prelive # or :production
+  config.client_id = 'your_client_id'
+  config.client_secret = 'your_client_secret'
+  config.scope = 'your_scope'
+end
+```
+
+## List Webhooks
+
+```ruby
+# Get all webhooks
+response = ZaiPayment.webhooks.list
+puts response.data # Array of webhooks
+puts response.meta # Pagination metadata
+
+# With pagination
+response = ZaiPayment.webhooks.list(limit: 20, offset: 10)
+```
+
+## Show a Specific Webhook
+
+```ruby
+webhook_id = 'webhook_123'
+response = ZaiPayment.webhooks.show(webhook_id)
+
+webhook = response.data
+puts webhook['id']
+puts webhook['url']
+puts webhook['object_type']
+puts webhook['enabled']
+```
+
+## Create a Webhook
+
+```ruby
+response = ZaiPayment.webhooks.create(
+  url: 'https://example.com/webhooks/zai',
+  object_type: 'transactions',
+  enabled: true,
+  description: 'Production webhook for transactions'
+)
+
+new_webhook = response.data
+puts "Created webhook with ID: #{new_webhook['id']}"
+```
+
+## Update a Webhook
+
+```ruby
+webhook_id = 'webhook_123'
+
+# Update specific fields
+response = ZaiPayment.webhooks.update(
+  webhook_id,
+  enabled: false,
+  description: 'Temporarily disabled'
+)
+
+# Or update multiple fields
+response = ZaiPayment.webhooks.update(
+  webhook_id,
+  url: 'https://example.com/webhooks/zai-v2',
+  object_type: 'items',
+  enabled: true
+)
+```
+
+## Delete a Webhook
+
+```ruby
+webhook_id = 'webhook_123'
+response = ZaiPayment.webhooks.delete(webhook_id)
+
+if response.success?
+  puts "Webhook deleted successfully"
+end
+```
+
+## Error Handling
+
+```ruby
+begin
+  response = ZaiPayment.webhooks.create(
+    url: 'https://example.com/webhook',
+    object_type: 'transactions'
+  )
+rescue ZaiPayment::Errors::ValidationError => e
+  puts "Validation error: #{e.message}"
+rescue ZaiPayment::Errors::UnauthorizedError => e
+  puts "Authentication failed: #{e.message}"
+rescue ZaiPayment::Errors::NotFoundError => e
+  puts "Resource not found: #{e.message}"
+rescue ZaiPayment::Errors::ApiError => e
+  puts "API error: #{e.message}"
+end
+```
+
+## Using Custom Client Instance
+
+If you need more control, you can create your own client instance:
+
+```ruby
+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)
+client = ZaiPayment::Client.new(config: config, token_provider: token_provider)
+
+webhooks = ZaiPayment::Resources::Webhook.new(client: client)
+response = webhooks.list
+```
+
+## Response Object
+
+All webhook methods return a `ZaiPayment::Response` object with the following methods:
+
+```ruby
+response = ZaiPayment.webhooks.list
+
+# Check status
+response.success?       # => true/false (2xx status)
+response.client_error?  # => true/false (4xx status)
+response.server_error?  # => true/false (5xx status)
+
+# Access data
+response.data           # => Main response data (array or hash)
+response.meta           # => Pagination metadata (if available)
+response.body           # => Raw response body
+response.headers        # => Response headers
+response.status         # => HTTP status code
+```
+

data/lib/zai_payment/client.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'faraday'
+
+module ZaiPayment
+  # Base API client that handles HTTP requests to Zai API
+  class Client
+    attr_reader :config, :token_provider
+
+    def initialize(config: nil, token_provider: nil)
+      @config = config || ZaiPayment.config
+      @token_provider = token_provider || ZaiPayment.auth
+    end
+
+    # Perform a GET request
+    #
+    # @param path [String] the API endpoint path
+    # @param params [Hash] query parameters
+    # @return [Response] the API response
+    def get(path, params: {})
+      request(:get, path, params: params)
+    end
+
+    # Perform a POST request
+    #
+    # @param path [String] the API endpoint path
+    # @param body [Hash] request body
+    # @return [Response] the API response
+    def post(path, body: {})
+      request(:post, path, body: body)
+    end
+
+    # Perform a PATCH request
+    #
+    # @param path [String] the API endpoint path
+    # @param body [Hash] request body
+    # @return [Response] the API response
+    def patch(path, body: {})
+      request(:patch, path, body: body)
+    end
+
+    # Perform a DELETE request
+    #
+    # @param path [String] the API endpoint path
+    # @return [Response] the API response
+    def delete(path)
+      request(:delete, path)
+    end
+
+    private
+
+    def request(method, path, params: {}, body: {})
+      response = connection.public_send(method) do |req|
+        req.url path
+        req.params = params if params.any?
+        req.body = body if body.any?
+      end
+
+      Response.new(response)
+    rescue Faraday::Error => e
+      handle_faraday_error(e)
+    end
+
+    def connection
+      @connection ||= build_connection
+    end
+
+    def build_connection
+      Faraday.new do |faraday|
+        configure_connection(faraday)
+      end
+    end
+
+    def configure_connection(faraday)
+      faraday.url_prefix = base_url
+      apply_headers(faraday)
+      apply_middleware(faraday)
+      apply_timeouts(faraday)
+      faraday.adapter Faraday.default_adapter
+    end
+
+    def apply_headers(faraday)
+      faraday.headers['Authorization'] = token_provider.bearer_token
+      faraday.headers['Content-Type'] = 'application/json'
+      faraday.headers['Accept'] = 'application/json'
+    end
+
+    def apply_middleware(faraday)
+      faraday.request :json
+      faraday.response :json, content_type: /\bjson$/
+    end
+
+    def apply_timeouts(faraday)
+      faraday.options.timeout = config.timeout if config.timeout
+      faraday.options.open_timeout = config.open_timeout if config.open_timeout
+    end
+
+    def base_url
+      # Webhooks API uses va_base endpoint
+      config.endpoints[:va_base]
+    end
+
+    def handle_faraday_error(error)
+      case error
+      when Faraday::TimeoutError
+        raise Errors::TimeoutError, "Request timed out: #{error.message}"
+      when Faraday::ConnectionFailed
+        raise Errors::ConnectionError, "Connection failed: #{error.message}"
+      when Faraday::ClientError
+        raise Errors::ApiError, "Client error: #{error.message}"
+      else
+        raise Errors::ApiError, "Request failed: #{error.message}"
+      end
+    end
+  end
+end

data/lib/zai_payment/config.rb

@@ -10,6 +10,8 @@ module ZaiPayment
       @client_id    = nil
       @client_secret = nil
       @scope = nil
+      @timeout = 10
+      @open_timeout = 10
     end
 
     def validate!

data/lib/zai_payment/errors.rb

@@ -2,8 +2,27 @@
 
 module ZaiPayment
   module Errors
+    # Base error class
     class Error < StandardError; end
+
+    # Authentication errors
     class AuthError < Error; end
+
+    # Configuration errors
     class ConfigurationError < Error; end
+
+    # API errors
+    class ApiError < Error; end
+    class BadRequestError < ApiError; end
+    class UnauthorizedError < ApiError; end
+    class ForbiddenError < ApiError; end
+    class NotFoundError < ApiError; end
+    class ValidationError < ApiError; end
+    class RateLimitError < ApiError; end
+    class ServerError < ApiError; end
+
+    # Network errors
+    class TimeoutError < Error; end
+    class ConnectionError < Error; end
   end
 end

data/lib/zai_payment/resources/webhook.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module ZaiPayment
+  module Resources
+    # Webhook resource for managing Zai webhooks
+    #
+    # @see https://developer.hellozai.com/reference/getallwebhooks
+    class Webhook
+      attr_reader :client
+
+      def initialize(client: nil)
+        @client = client || Client.new
+      end
+
+      # List all webhooks
+      #
+      # @param limit [Integer] number of records to return (default: 10)
+      # @param offset [Integer] number of records to skip (default: 0)
+      # @return [Response] the API response containing webhooks array
+      #
+      # @example
+      #   webhooks = ZaiPayment::Resources::Webhook.new
+      #   response = webhooks.list
+      #   response.data # => [{"id" => "...", "url" => "..."}, ...]
+      #
+      # @see https://developer.hellozai.com/reference/getallwebhooks
+      def list(limit: 10, offset: 0)
+        params = {
+          limit: limit,
+          offset: offset
+        }
+
+        client.get('/webhooks', params: params)
+      end
+
+      # Get a specific webhook by ID
+      #
+      # @param webhook_id [String] the webhook ID
+      # @return [Response] the API response containing webhook details
+      #
+      # @example
+      #   webhooks = ZaiPayment::Resources::Webhook.new
+      #   response = webhooks.show("webhook_id")
+      #   response.data # => {"id" => "webhook_id", "url" => "...", ...}
+      #
+      # @see https://developer.hellozai.com/reference/getwebhookbyid
+      def show(webhook_id)
+        validate_id!(webhook_id, 'webhook_id')
+        client.get("/webhooks/#{webhook_id}")
+      end
+
+      # Create a new webhook
+      #
+      # @param url [String] the webhook URL to receive notifications
+      # @param object_type [String] the type of object to watch (e.g., 'transactions', 'items')
+      # @param enabled [Boolean] whether the webhook is enabled (default: true)
+      # @param description [String] optional description of the webhook
+      # @return [Response] the API response containing created webhook
+      #
+      # @example
+      #   webhooks = ZaiPayment::Resources::Webhook.new
+      #   response = webhooks.create(
+      #     url: "https://example.com/webhooks",
+      #     object_type: "transactions",
+      #     enabled: true
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/createwebhook
+      def create(url: nil, object_type: nil, enabled: true, description: nil)
+        validate_presence!(url, 'url')
+        validate_presence!(object_type, 'object_type')
+        validate_url!(url)
+
+        body = {
+          url: url,
+          object_type: object_type,
+          enabled: enabled
+        }
+
+        body[:description] = description if description
+
+        client.post('/webhooks', body: body)
+      end
+
+      # Update an existing webhook
+      #
+      # @param webhook_id [String] the webhook ID
+      # @param url [String] optional new webhook URL
+      # @param object_type [String] optional new object type
+      # @param enabled [Boolean] optional enabled status
+      # @param description [String] optional description
+      # @return [Response] the API response containing updated webhook
+      #
+      # @example
+      #   webhooks = ZaiPayment::Resources::Webhook.new
+      #   response = webhooks.update(
+      #     "webhook_id",
+      #     enabled: false
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/updatewebhook
+      def update(webhook_id, url: nil, object_type: nil, enabled: nil, description: nil)
+        validate_id!(webhook_id, 'webhook_id')
+
+        body = {}
+        body[:url] = url if url
+        body[:object_type] = object_type if object_type
+        body[:enabled] = enabled unless enabled.nil?
+        body[:description] = description if description
+
+        validate_url!(url) if url
+
+        raise Errors::ValidationError, 'At least one attribute must be provided for update' if body.empty?
+
+        client.patch("/webhooks/#{webhook_id}", body: body)
+      end
+
+      # Delete a webhook
+      #
+      # @param webhook_id [String] the webhook ID
+      # @return [Response] the API response
+      #
+      # @example
+      #   webhooks = ZaiPayment::Resources::Webhook.new
+      #   response = webhooks.delete("webhook_id")
+      #
+      # @see https://developer.hellozai.com/reference/deletewebhook
+      def delete(webhook_id)
+        validate_id!(webhook_id, 'webhook_id')
+        client.delete("/webhooks/#{webhook_id}")
+      end
+
+      private
+
+      def validate_id!(value, field_name)
+        return unless value.nil? || value.to_s.strip.empty?
+
+        raise Errors::ValidationError, "#{field_name} is required and cannot be blank"
+      end
+
+      def validate_presence!(value, field_name)
+        return unless value.nil? || value.to_s.strip.empty?
+
+        raise Errors::ValidationError, "#{field_name} is required and cannot be blank"
+      end
+
+      def validate_url!(url)
+        uri = URI.parse(url)
+        unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+          raise Errors::ValidationError, 'url must be a valid HTTP or HTTPS URL'
+        end
+      rescue URI::InvalidURIError
+        raise Errors::ValidationError, 'url must be a valid URL'
+      end
+    end
+  end
+end

data/lib/zai_payment/response.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module ZaiPayment
+  # Wrapper for API responses
+  class Response
+    attr_reader :status, :body, :headers, :raw_response
+
+    def initialize(faraday_response)
+      @raw_response = faraday_response
+      @status = faraday_response.status
+      @body = faraday_response.body
+      @headers = faraday_response.headers
+
+      check_for_errors!
+    end
+
+    # Check if the response was successful (2xx status)
+    def success?
+      (200..299).cover?(status)
+    end
+
+    # Check if the response was a client error (4xx status)
+    def client_error?
+      (400..499).cover?(status)
+    end
+
+    # Check if the response was a server error (5xx status)
+    def server_error?
+      (500..599).cover?(status)
+    end
+
+    # Get the data from the response body
+    def data
+      body.is_a?(Hash) ? body['webhooks'] || body : body
+    end
+
+    # Get pagination or metadata info
+    def meta
+      body.is_a?(Hash) ? body['meta'] : nil
+    end
+
+    ERROR_STATUS_MAP = {
+      400 => Errors::BadRequestError,
+      401 => Errors::UnauthorizedError,
+      403 => Errors::ForbiddenError,
+      404 => Errors::NotFoundError,
+      422 => Errors::ValidationError,
+      429 => Errors::RateLimitError
+    }.merge((500..599).to_h { |code| [code, Errors::ServerError] }).freeze
+
+    private
+
+    def check_for_errors!
+      return if success?
+
+      raise_appropriate_error
+    end
+
+    def raise_appropriate_error
+      error_message = extract_error_message
+      error_class = error_class_for_status
+      raise error_class, error_message
+    end
+
+    def error_class_for_status
+      ERROR_STATUS_MAP.fetch(status, Errors::ApiError)
+    end
+
+    def extract_error_message
+      if body.is_a?(Hash)
+        body['error'] || body['message'] || body['errors']&.join(', ') || "HTTP #{status}"
+      else
+        "HTTP #{status}: #{body}"
+      end
+    end
+  end
+end

data/lib/zai_payment/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ZaiPayment
-  VERSION = '1.0.1'
+  VERSION = '1.1.0'
 end