zai_payment 1.0.2 → 1.2.0

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,331 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'base64'
+
+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
+
+      # Create a secret key for webhook signature verification
+      #
+      # @param secret_key [String] the secret key to use for HMAC signature generation
+      #   Must be ASCII characters and at least 32 bytes in size
+      # @return [Response] the API response
+      #
+      # @example
+      #   webhooks = ZaiPayment::Resources::Webhook.new
+      #   secret_key = SecureRandom.alphanumeric(32)
+      #   response = webhooks.create_secret_key(secret_key: secret_key)
+      #
+      # @see https://developer.hellozai.com/reference/createsecretkey
+      # @see https://developer.hellozai.com/docs/verify-webhook-signatures
+      def create_secret_key(secret_key:)
+        validate_presence!(secret_key, 'secret_key')
+        validate_secret_key!(secret_key)
+
+        body = { secret_key: secret_key }
+        client.post('/webhooks/secret_key', body: body)
+      end
+
+      # Verify webhook signature
+      #
+      # This method verifies that a webhook request came from Zai by validating
+      # the HMAC SHA256 signature in the Webhooks-signature header.
+      #
+      # @param payload [String] the raw request body (JSON string)
+      # @param signature_header [String] the Webhooks-signature header value
+      # @param secret_key [String] your secret key used for signature generation
+      # @param tolerance [Integer] maximum age of webhook in seconds (default: 300 = 5 minutes)
+      # @return [Boolean] true if signature is valid and within tolerance
+      # @raise [Errors::ValidationError] if signature is invalid or timestamp is outside tolerance
+      #
+      # @example
+      #   # In your webhook endpoint (e.g., Rails controller)
+      #   def webhook
+      #     payload = request.body.read
+      #     signature_header = request.headers['Webhooks-signature']
+      #     secret_key = ENV['ZAI_WEBHOOK_SECRET']
+      #
+      #     if ZaiPayment.webhooks.verify_signature(
+      #       payload: payload,
+      #       signature_header: signature_header,
+      #       secret_key: secret_key
+      #     )
+      #       # Process webhook
+      #       render json: { status: 'success' }
+      #     else
+      #       render json: { error: 'Invalid signature' }, status: :unauthorized
+      #     end
+      #   end
+      #
+      # @see https://developer.hellozai.com/docs/verify-webhook-signatures
+      def verify_signature(payload:, signature_header:, secret_key:, tolerance: 300)
+        validate_presence!(payload, 'payload')
+        validate_presence!(signature_header, 'signature_header')
+        validate_presence!(secret_key, 'secret_key')
+
+        # Extract timestamp and signature from header
+        timestamp, signatures = parse_signature_header(signature_header)
+
+        # Verify timestamp is within tolerance (prevent replay attacks)
+        verify_timestamp!(timestamp, tolerance)
+
+        # Generate expected signature
+        expected_signature = generate_signature(payload, secret_key, timestamp)
+
+        # Compare signatures using constant-time comparison
+        signatures.any? { |sig| secure_compare(expected_signature, sig) }
+      end
+
+      # Generate a signature for webhook verification
+      #
+      # This is a utility method that can be used for testing or generating
+      # signatures for webhook simulation.
+      #
+      # @param payload [String] the request body (JSON string)
+      # @param secret_key [String] the secret key
+      # @param timestamp [Integer] the Unix timestamp (defaults to current time)
+      # @return [String] the base64url-encoded HMAC SHA256 signature
+      #
+      # @example
+      #   webhooks = ZaiPayment::Resources::Webhook.new
+      #   signature = webhooks.generate_signature(
+      #     '{"event": "status_updated"}',
+      #     'my_secret_key'
+      #   )
+      #
+      # @see https://developer.hellozai.com/docs/verify-webhook-signatures
+      def generate_signature(payload, secret_key, timestamp = Time.now.to_i)
+        signed_payload = "#{timestamp}.#{payload}"
+        digest = OpenSSL::Digest.new('sha256')
+        hash = OpenSSL::HMAC.digest(digest, secret_key, signed_payload)
+        Base64.urlsafe_encode64(hash, padding: false)
+      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
+
+      def validate_secret_key!(secret_key)
+        # Check if it's ASCII
+        raise Errors::ValidationError, 'secret_key must contain only ASCII characters' unless secret_key.ascii_only?
+
+        # Check minimum length (32 bytes)
+        return unless secret_key.bytesize < 32
+
+        raise Errors::ValidationError, 'secret_key must be at least 32 bytes in size'
+      end
+
+      def parse_signature_header(header)
+        # Format: "t=1257894000,v=signature1,v=signature2"
+        parts = header.split(',').map(&:strip)
+
+        timestamp, signatures = extract_timestamp_and_signatures(parts)
+
+        validate_timestamp_presence!(timestamp)
+        validate_signatures_presence!(signatures)
+
+        [timestamp, signatures]
+      end
+
+      def extract_timestamp_and_signatures(parts)
+        timestamp = nil
+        signatures = []
+
+        parts.each do |part|
+          key, value = part.split('=', 2)
+          case key
+          when 't'
+            timestamp = value.to_i
+          when 'v'
+            signatures << value
+          end
+        end
+
+        [timestamp, signatures]
+      end
+
+      def validate_timestamp_presence!(timestamp)
+        return unless timestamp.nil? || timestamp.zero?
+
+        raise Errors::ValidationError, 'Invalid signature header: missing or invalid timestamp'
+      end
+
+      def validate_signatures_presence!(signatures)
+        raise Errors::ValidationError, 'Invalid signature header: missing signature' if signatures.empty?
+      end
+
+      def verify_timestamp!(timestamp, tolerance)
+        current_time = Time.now.to_i
+        time_diff = (current_time - timestamp).abs
+
+        return unless time_diff > tolerance
+
+        raise Errors::ValidationError,
+              "Webhook timestamp is outside tolerance (#{time_diff}s vs #{tolerance}s max). " \
+              'This may be a replay attack.'
+      end
+
+      # Constant-time string comparison to prevent timing attacks
+      # Uses OpenSSL's secure_compare if available, otherwise falls back to manual comparison
+      def secure_compare(str_a, str_b)
+        return false unless str_a.bytesize == str_b.bytesize
+
+        if defined?(OpenSSL.fixed_length_secure_compare)
+          OpenSSL.fixed_length_secure_compare(str_a, str_b)
+        else
+          # Fallback for older Ruby versions
+          result = 0
+          str_a.bytes.zip(str_b.bytes) { |x, y| result |= x ^ y }
+          result.zero?
+        end
+      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.2'
+  VERSION = '1.2.0'
 end

data/lib/zai_payment.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
 require 'faraday'
+require 'uri'
 require_relative 'zai_payment/version'
 require_relative 'zai_payment/config'
 require_relative 'zai_payment/errors'
 require_relative 'zai_payment/auth/token_provider'
 require_relative 'zai_payment/auth/token_store'
 require_relative 'zai_payment/auth/token_stores/memory_store'
+require_relative 'zai_payment/client'
+require_relative 'zai_payment/response'
+require_relative 'zai_payment/resources/webhook'
 
 module ZaiPayment
   class << self
@@ -29,5 +33,11 @@ module ZaiPayment
     def clear_token!     = auth.clear_token
     def token_expiry     = auth.token_expiry
     def token_type       = auth.token_type
+
+    # --- Resource accessors ---
+    # @return [ZaiPayment::Resources::Webhook] webhook resource instance
+    def webhooks
+      @webhooks ||= Resources::Webhook.new
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zai_payment
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.2.0
 platform: ruby
 authors:
 - Eddy Jaga
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.0
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -23,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: openssl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
 description: A Ruby gem for integrating with Zai payment platform APIs.
 email:
 - eddy.jaga@sentia.com.au
@@ -32,15 +60,26 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- IMPLEMENTATION.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/ARCHITECTURE.md
+- docs/AUTHENTICATION.md
+- docs/README.md
+- docs/WEBHOOKS.md
+- docs/WEBHOOK_SECURITY_QUICKSTART.md
+- docs/WEBHOOK_SIGNATURE.md
+- examples/webhooks.md
 - lib/zai_payment.rb
 - lib/zai_payment/auth/token_provider.rb
 - lib/zai_payment/auth/token_store.rb
 - lib/zai_payment/auth/token_stores/memory_store.rb
+- lib/zai_payment/client.rb
 - lib/zai_payment/config.rb
 - lib/zai_payment/errors.rb
+- lib/zai_payment/resources/webhook.rb
+- lib/zai_payment/response.rb
 - lib/zai_payment/version.rb
 - sig/zai_payment.rbs
 homepage: https://github.com/Sentia/zai-payment