zai_payment 1.1.0 → 1.3.0

data/lib/zai_payment/resources/user.rb

@@ -0,0 +1,383 @@
+# frozen_string_literal: true
+
+module ZaiPayment
+  module Resources
+    # User resource for managing Zai users (payin and payout)
+    #
+    # @see https://developer.hellozai.com/docs/onboarding-a-payin-user
+    # @see https://developer.hellozai.com/docs/onboarding-a-payout-user
+    class User
+      attr_reader :client
+
+      # User types
+      USER_TYPE_PAYIN = 'payin'
+      USER_TYPE_PAYOUT = 'payout'
+
+      # Valid user types
+      VALID_USER_TYPES = [USER_TYPE_PAYIN, USER_TYPE_PAYOUT].freeze
+
+      # Map of attribute keys to API field names
+      FIELD_MAPPING = {
+        id: :id,
+        email: :email,
+        first_name: :first_name,
+        last_name: :last_name,
+        mobile: :mobile,
+        phone: :phone,
+        address_line1: :address_line1,
+        address_line2: :address_line2,
+        city: :city,
+        state: :state,
+        zip: :zip,
+        country: :country,
+        dob: :dob,
+        government_number: :government_number,
+        drivers_license_number: :drivers_license_number,
+        drivers_license_state: :drivers_license_state,
+        logo_url: :logo_url,
+        color_1: :color_1,
+        color_2: :color_2,
+        custom_descriptor: :custom_descriptor,
+        authorized_signer_title: :authorized_signer_title,
+        user_type: :user_type,
+        device_id: :device_id,
+        ip_address: :ip_address
+      }.freeze
+
+      # Map of company attribute keys to API field names
+      COMPANY_FIELD_MAPPING = {
+        name: :name,
+        legal_name: :legal_name,
+        tax_number: :tax_number,
+        business_email: :business_email,
+        charge_tax: :charge_tax,
+        address_line1: :address_line1,
+        address_line2: :address_line2,
+        city: :city,
+        state: :state,
+        zip: :zip,
+        country: :country,
+        phone: :phone
+      }.freeze
+
+      def initialize(client: nil)
+        @client = client || Client.new
+      end
+
+      # List all users
+      #
+      # @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 users array
+      #
+      # @example
+      #   users = ZaiPayment::Resources::User.new
+      #   response = users.list
+      #   response.data # => [{"id" => "...", "email" => "..."}, ...]
+      #
+      # @see https://developer.hellozai.com/reference/getallusers
+      def list(limit: 10, offset: 0)
+        params = {
+          limit: limit,
+          offset: offset
+        }
+
+        client.get('/users', params: params)
+      end
+
+      # Get a specific user by ID
+      #
+      # @param user_id [String] the user ID
+      # @return [Response] the API response containing user details
+      #
+      # @example
+      #   users = ZaiPayment::Resources::User.new
+      #   response = users.show("user_id")
+      #   response.data # => {"id" => "user_id", "email" => "...", ...}
+      #
+      # @see https://developer.hellozai.com/reference/getuserbyid
+      def show(user_id)
+        validate_id!(user_id, 'user_id')
+        client.get("/users/#{user_id}")
+      end
+
+      # Create a new user (payin or payout)
+      #
+      # @param attributes [Hash] user attributes
+      # @option attributes [String] :id Optional unique ID for the user. If not provided,
+      #   Zai will generate one automatically. Cannot contain '.' character.
+      #   Useful for mapping to your existing system's user IDs.
+      # @option attributes [String] :email (Required) user's email address
+      # @option attributes [String] :first_name (Required) user's first name
+      # @option attributes [String] :last_name (Required) user's last name
+      # @option attributes [String] :country (Required) user's country code (ISO 3166-1 alpha-3)
+      # @option attributes [String] :user_type Optional user type ('payin' or 'payout')
+      # @option attributes [String] :mobile user's mobile phone number (international format with '+')
+      # @option attributes [String] :phone user's phone number
+      # @option attributes [String] :address_line1 user's address line 1
+      # @option attributes [String] :address_line2 user's address line 2
+      # @option attributes [String] :city user's city
+      # @option attributes [String] :state user's state
+      # @option attributes [String] :zip user's postal/zip code
+      # @option attributes [String] :dob user's date of birth (DD/MM/YYYY)
+      # @option attributes [String] :government_number user's government ID number (SSN, TFN, etc.)
+      # @option attributes [String] :drivers_license_number driving license number
+      # @option attributes [String] :drivers_license_state state section of the user's driving license
+      # @option attributes [String] :logo_url URL link to the logo
+      # @option attributes [String] :color_1 color code number 1
+      # @option attributes [String] :color_2 color code number 2
+      # @option attributes [String] :custom_descriptor custom descriptor for bundle direct debit statements
+      # @option attributes [String] :authorized_signer_title job title for AMEX merchants (e.g., Director)
+      # @option attributes [Hash] :company company details (creates a company for the user)
+      # @option attributes [String] :device_id device ID for fraud prevention
+      # @option attributes [String] :ip_address IP address for fraud prevention
+      # @return [Response] the API response containing created user
+      #
+      # @example Create a payin user (buyer) with auto-generated ID
+      #   users = ZaiPayment::Resources::User.new
+      #   response = users.create(
+      #     email: "buyer@example.com",
+      #     first_name: "John",
+      #     last_name: "Doe",
+      #     country: "USA",
+      #     mobile: "+1234567890",
+      #     address_line1: "123 Main St",
+      #     city: "New York",
+      #     state: "NY",
+      #     zip: "10001"
+      #   )
+      #
+      # @example Create a payin user with custom ID
+      #   users = ZaiPayment::Resources::User.new
+      #   response = users.create(
+      #     id: "buyer-#{your_user_id}",
+      #     email: "buyer@example.com",
+      #     first_name: "John",
+      #     last_name: "Doe",
+      #     country: "USA"
+      #   )
+      #
+      # @example Create a payout user (seller/merchant)
+      #   users = ZaiPayment::Resources::User.new
+      #   response = 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",
+      #     mobile: "+61412345678"
+      #   )
+      #
+      # @example Create a user with company details
+      #   users = ZaiPayment::Resources::User.new
+      #   response = users.create(
+      #     email: "business@example.com",
+      #     first_name: "John",
+      #     last_name: "Doe",
+      #     country: "AUS",
+      #     mobile: "+61412345678",
+      #     authorized_signer_title: "Director",
+      #     company: {
+      #       name: "ABC Company",
+      #       legal_name: "ABC Pty Ltd",
+      #       tax_number: "123456789",
+      #       business_email: "admin@abc.com",
+      #       country: "AUS",
+      #       charge_tax: true,
+      #       address_line1: "123 Business St",
+      #       city: "Melbourne",
+      #       state: "VIC",
+      #       zip: "3000",
+      #       phone: "+61398765432"
+      #     }
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/createuser
+      # @see https://developer.hellozai.com/docs/onboarding-a-payin-user
+      # @see https://developer.hellozai.com/docs/onboarding-a-payout-user
+      def create(**attributes)
+        validate_create_attributes!(attributes)
+
+        body = build_user_body(attributes)
+        client.post('/users', body: body)
+      end
+
+      # Update an existing user
+      #
+      # @param user_id [String] the user ID
+      # @param attributes [Hash] user attributes to update
+      # @option attributes [String] :email user's email address
+      # @option attributes [String] :first_name user's first name
+      # @option attributes [String] :last_name user's last name
+      # @option attributes [String] :mobile user's mobile phone number (international format with '+')
+      # @option attributes [String] :phone user's phone number
+      # @option attributes [String] :address_line1 user's address line 1
+      # @option attributes [String] :address_line2 user's address line 2
+      # @option attributes [String] :city user's city
+      # @option attributes [String] :state user's state
+      # @option attributes [String] :zip user's postal/zip code
+      # @option attributes [String] :dob user's date of birth (DD/MM/YYYY)
+      # @option attributes [String] :government_number user's government ID number (SSN, TFN, etc.)
+      # @option attributes [String] :drivers_license_number driving license number
+      # @option attributes [String] :drivers_license_state state section of the user's driving license
+      # @option attributes [String] :logo_url URL link to the logo
+      # @option attributes [String] :color_1 color code number 1
+      # @option attributes [String] :color_2 color code number 2
+      # @option attributes [String] :custom_descriptor custom descriptor for bundle direct debit statements
+      # @option attributes [String] :authorized_signer_title job title for AMEX merchants (e.g., Director)
+      # @return [Response] the API response containing updated user
+      #
+      # @example
+      #   users = ZaiPayment::Resources::User.new
+      #   response = users.update(
+      #     "user_id",
+      #     mobile: "+1234567890",
+      #     address_line1: "789 New St"
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/updateuser
+      def update(user_id, **attributes)
+        validate_id!(user_id, 'user_id')
+
+        body = build_user_body(attributes)
+
+        validate_email!(attributes[:email]) if attributes[:email]
+        validate_dob!(attributes[:dob]) if attributes[:dob]
+
+        raise Errors::ValidationError, 'At least one attribute must be provided for update' if body.empty?
+
+        client.patch("/users/#{user_id}", body: body)
+      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_create_attributes!(attributes) # rubocop:disable Metrics/AbcSize
+        validate_required_attributes!(attributes)
+        validate_user_type!(attributes[:user_type]) if attributes[:user_type]
+        validate_email!(attributes[:email])
+        validate_country!(attributes[:country])
+        validate_dob!(attributes[:dob]) if attributes[:dob]
+        validate_user_id!(attributes[:id]) if attributes[:id]
+        validate_company!(attributes[:company]) if attributes[:company]
+      end
+
+      def validate_required_attributes!(attributes)
+        required_fields = %i[email first_name last_name country]
+
+        missing_fields = required_fields.select do |field|
+          attributes[field].nil? || attributes[field].to_s.strip.empty?
+        end
+
+        return if missing_fields.empty?
+
+        raise Errors::ValidationError,
+              "Missing required fields: #{missing_fields.join(', ')}"
+      end
+
+      def validate_user_type!(user_type)
+        return if VALID_USER_TYPES.include?(user_type.to_s.downcase)
+
+        raise Errors::ValidationError,
+              "user_type must be one of: #{VALID_USER_TYPES.join(', ')}"
+      end
+
+      def validate_email!(email)
+        # Basic email format validation
+        email_regex = /\A[^@\s]+@[^@\s]+\.[^@\s]+\z/
+        return if email&.match?(email_regex)
+
+        raise Errors::ValidationError, 'email must be a valid email address'
+      end
+
+      def validate_country!(country)
+        # Country should be ISO 3166-1 alpha-3 code (3 letters)
+        return if country.to_s.match?(/\A[A-Z]{3}\z/i)
+
+        raise Errors::ValidationError, 'country must be a valid ISO 3166-1 alpha-3 code (e.g., USA, AUS, GBR)'
+      end
+
+      def validate_dob!(dob)
+        # Date of birth should be in DD/MM/YYYY format
+        return if dob.to_s.match?(%r{\A\d{2}/\d{2}/\d{4}\z})
+
+        raise Errors::ValidationError, 'dob must be in DD/MM/YYYY format (e.g., 15/01/1990)'
+      end
+
+      def validate_user_id!(user_id)
+        # User ID cannot contain '.' character
+        raise Errors::ValidationError, "id cannot contain '.' character" if user_id.to_s.include?('.')
+
+        # Check if empty
+        return unless user_id.nil? || user_id.to_s.strip.empty?
+
+        raise Errors::ValidationError, 'id cannot be blank if provided'
+      end
+
+      def validate_company!(company)
+        return unless company.is_a?(Hash)
+
+        # Required company fields
+        required_company_fields = %i[name legal_name tax_number business_email country]
+
+        missing_fields = required_company_fields.select do |field|
+          company[field].nil? || company[field].to_s.strip.empty?
+        end
+
+        return if missing_fields.empty?
+
+        raise Errors::ValidationError,
+              "Company is missing required fields: #{missing_fields.join(', ')}"
+      end
+
+      def build_user_body(attributes) # rubocop:disable Metrics/CyclomaticComplexity
+        body = {}
+
+        attributes.each do |key, value|
+          next if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+          # Handle company object separately
+          if key == :company
+            body[:company] = build_company_body(value) if value.is_a?(Hash)
+            next
+          end
+
+          api_field = FIELD_MAPPING[key]
+          body[api_field] = value if api_field
+        end
+
+        body
+      end
+
+      def build_company_body(company_attributes)
+        company = {}
+
+        company_attributes.each do |key, value|
+          # Don't skip false values for charge_tax
+          next if value.nil?
+          next if key != :charge_tax && value.respond_to?(:empty?) && value.empty?
+
+          api_field = COMPANY_FIELD_MAPPING[key]
+          company[api_field] = value if api_field
+        end
+
+        company
+      end
+    end
+  end
+end

data/lib/zai_payment/resources/webhook.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'openssl'
+require 'base64'
+
 module ZaiPayment
   module Resources
     # Webhook resource for managing Zai webhooks
@@ -130,6 +133,102 @@ module ZaiPayment
         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)
@@ -152,6 +251,81 @@ module ZaiPayment
       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

@@ -31,7 +31,7 @@ module ZaiPayment
 
     # Get the data from the response body
     def data
-      body.is_a?(Hash) ? body['webhooks'] || body : body
+      body.is_a?(Hash) ? body['webhooks'] || body['users'] || body : body
     end
 
     # Get pagination or metadata info

data/lib/zai_payment/version.rb

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

data/lib/zai_payment.rb

@@ -11,6 +11,7 @@ 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'
+require_relative 'zai_payment/resources/user'
 
 module ZaiPayment
   class << self
@@ -39,5 +40,10 @@ module ZaiPayment
     def webhooks
       @webhooks ||= Resources::Webhook.new
     end
+
+    # @return [ZaiPayment::Resources::User] user resource instance
+    def users
+      @users ||= Resources::User.new(client: Client.new(base_endpoint: :core_base))
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zai_payment
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.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,12 +60,24 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
 - IMPLEMENTATION.md
+- IMPLEMENTATION_SUMMARY.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- badges/.gitkeep
+- badges/coverage.json
 - docs/ARCHITECTURE.md
+- docs/AUTHENTICATION.md
+- docs/README.md
+- docs/USERS.md
+- docs/USER_ID_FIELD.md
+- docs/USER_QUICK_REFERENCE.md
 - docs/WEBHOOKS.md
+- docs/WEBHOOK_SECURITY_QUICKSTART.md
+- docs/WEBHOOK_SIGNATURE.md
+- examples/users.md
 - examples/webhooks.md
 - lib/zai_payment.rb
 - lib/zai_payment/auth/token_provider.rb
@@ -46,6 +86,7 @@ files:
 - lib/zai_payment/client.rb
 - lib/zai_payment/config.rb
 - lib/zai_payment/errors.rb
+- lib/zai_payment/resources/user.rb
 - lib/zai_payment/resources/webhook.rb
 - lib/zai_payment/response.rb
 - lib/zai_payment/version.rb