zai_payment 1.3.2 → 2.0.0

data/lib/zai_payment/resources/item.rb

@@ -0,0 +1,363 @@
+# frozen_string_literal: true
+
+module ZaiPayment
+  module Resources
+    # Item resource for managing Zai items (transactions/payments)
+    #
+    # @see https://developer.hellozai.com/reference/listitems
+    class Item
+      attr_reader :client
+
+      # Map of attribute keys to API field names
+      FIELD_MAPPING = {
+        id: :id,
+        name: :name,
+        amount: :amount,
+        payment_type: :payment_type,
+        buyer_id: :buyer_id,
+        seller_id: :seller_id,
+        fee_ids: :fee_ids,
+        description: :description,
+        currency: :currency,
+        custom_descriptor: :custom_descriptor,
+        buyer_url: :buyer_url,
+        seller_url: :seller_url,
+        tax_invoice: :tax_invoice
+      }.freeze
+
+      def initialize(client: nil)
+        @client = client || Client.new
+      end
+
+      # List all items
+      #
+      # @param limit [Integer] number of records to return (default: 10, max: 200)
+      # @param offset [Integer] number of records to skip (default: 0)
+      # @param search [String] optional text value to search within item description
+      # @param created_before [String] optional ISO 8601 date/time to filter items created before
+      #   (e.g. '2020-02-27T23:54:59Z')
+      # @param created_after [String] optional ISO 8601 date/time to filter items created after
+      #   (e.g. '2020-02-27T23:54:59Z')
+      # @return [Response] the API response containing items array
+      #
+      # @example List all items
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.list
+      #   response.data # => [{"id" => "...", "name" => "..."}, ...]
+      #
+      # @example List items with search
+      #   response = items.list(search: "product")
+      #
+      # @example List items created within a date range
+      #   response = items.list(
+      #     created_after: "2024-01-01T00:00:00Z",
+      #     created_before: "2024-12-31T23:59:59Z"
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/listitems
+      def list(limit: 10, offset: 0, search: nil, created_before: nil, created_after: nil)
+        params = {
+          limit: limit,
+          offset: offset
+        }
+
+        params[:search] = search if search
+        params[:created_before] = created_before if created_before
+        params[:created_after] = created_after if created_after
+
+        client.get('/items', params: params)
+      end
+
+      # Get a specific item by ID
+      #
+      # @param item_id [String] the item ID
+      # @return [Response] the API response containing item details
+      #
+      # @example
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.show("item_id")
+      #   response.data # => {"items" => {"id" => "item_id", "name" => "...", ...}}
+      #
+      # @see https://developer.hellozai.com/reference/showitem
+      def show(item_id)
+        validate_id!(item_id, 'item_id')
+        client.get("/items/#{item_id}")
+      end
+
+      # Create a new item
+      #
+      # @param attributes [Hash] item attributes
+      # @option attributes [String] :id Optional unique ID for the item
+      # @option attributes [String] :name (Required) Name of the item
+      # @option attributes [Integer] :amount (Required) Amount in cents
+      # @option attributes [String] :payment_type (Required) Payment type (1-7, default: 2)
+      # @option attributes [String] :buyer_id (Required) Buyer user ID
+      # @option attributes [String] :seller_id (Required) Seller user ID
+      # @option attributes [Array<String>] :fee_ids Optional array of fee IDs
+      # @option attributes [String] :description Optional description
+      # @option attributes [String] :currency Optional currency code (e.g., 'AUD')
+      # @option attributes [String] :custom_descriptor Optional custom descriptor
+      # @option attributes [String] :buyer_url Optional buyer URL
+      # @option attributes [String] :seller_url Optional seller URL
+      # @option attributes [Boolean] :tax_invoice Optional tax invoice flag
+      # @return [Response] the API response containing created item
+      #
+      # @example
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.create(
+      #     name: "Product Purchase",
+      #     amount: 10000,
+      #     payment_type: 2,
+      #     buyer_id: "buyer-123",
+      #     seller_id: "seller-456",
+      #     description: "Purchase of product XYZ"
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/createitem
+      def create(**attributes)
+        validate_create_attributes!(attributes)
+
+        body = build_item_body(attributes)
+        client.post('/items', body: body)
+      end
+
+      # Update an existing item
+      #
+      # @param item_id [String] the item ID
+      # @param attributes [Hash] item attributes to update
+      # @option attributes [String] :name Name of the item
+      # @option attributes [Integer] :amount Amount in cents
+      # @option attributes [String] :description Description
+      # @option attributes [String] :buyer_id Buyer user ID
+      # @option attributes [String] :seller_id Seller user ID
+      # @option attributes [Array<String>] :fee_ids Array of fee IDs
+      # @option attributes [String] :custom_descriptor Custom descriptor
+      # @option attributes [String] :buyer_url Buyer URL
+      # @option attributes [String] :seller_url Seller URL
+      # @option attributes [Boolean] :tax_invoice Tax invoice flag
+      # @return [Response] the API response containing updated item
+      #
+      # @example
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.update(
+      #     "item_id",
+      #     name: "Updated Product Name",
+      #     description: "Updated description"
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/updateitem
+      def update(item_id, **attributes)
+        validate_id!(item_id, 'item_id')
+
+        body = build_item_body(attributes)
+
+        raise Errors::ValidationError, 'At least one attribute must be provided for update' if body.empty?
+
+        client.patch("/items/#{item_id}", body: body)
+      end
+
+      # Delete an item
+      #
+      # @param item_id [String] the item ID
+      # @return [Response] the API response
+      #
+      # @example
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.delete("item_id")
+      #
+      # @see https://developer.hellozai.com/reference/deleteitem
+      def delete(item_id)
+        validate_id!(item_id, 'item_id')
+        client.delete("/items/#{item_id}")
+      end
+
+      # Show item seller
+      #
+      # @param item_id [String] the item ID
+      # @return [Response] the API response containing seller details
+      #
+      # @example
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.show_seller("item_id")
+      #   response.data # => {"users" => {"id" => "...", "email" => "...", ...}}
+      #
+      # @see https://developer.hellozai.com/reference/showitemseller
+      def show_seller(item_id)
+        validate_id!(item_id, 'item_id')
+        client.get("/items/#{item_id}/sellers")
+      end
+
+      # Show item buyer
+      #
+      # @param item_id [String] the item ID
+      # @return [Response] the API response containing buyer details
+      #
+      # @example
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.show_buyer("item_id")
+      #   response.data # => {"users" => {"id" => "...", "email" => "...", ...}}
+      #
+      # @see https://developer.hellozai.com/reference/showitembuyer
+      def show_buyer(item_id)
+        validate_id!(item_id, 'item_id')
+        client.get("/items/#{item_id}/buyers")
+      end
+
+      # Show item fees
+      #
+      # @param item_id [String] the item ID
+      # @return [Response] the API response containing fees details
+      #
+      # @example
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.show_fees("item_id")
+      #   response.data # => {"fees" => [{"id" => "...", "amount" => "...", ...}]}
+      #
+      # @see https://developer.hellozai.com/reference/showitemfees
+      def show_fees(item_id)
+        validate_id!(item_id, 'item_id')
+        client.get("/items/#{item_id}/fees")
+      end
+
+      # Show item wire details
+      #
+      # @param item_id [String] the item ID
+      # @return [Response] the API response containing wire transfer details
+      #
+      # @example
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.show_wire_details("item_id")
+      #   response.data # => {"items" => {"wire_details" => {...}}}
+      #
+      # @see https://developer.hellozai.com/reference/showitemwiredetails
+      def show_wire_details(item_id)
+        validate_id!(item_id, 'item_id')
+        client.get("/items/#{item_id}/wire_details")
+      end
+
+      # List item transactions
+      #
+      # @param item_id [String] the item ID
+      # @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 transactions array
+      #
+      # @example
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.list_transactions("item_id")
+      #   response.data # => {"transactions" => [{"id" => "...", "amount" => "...", ...}]}
+      #
+      # @see https://developer.hellozai.com/reference/listitemtransactions
+      def list_transactions(item_id, limit: 10, offset: 0)
+        validate_id!(item_id, 'item_id')
+
+        params = {
+          limit: limit,
+          offset: offset
+        }
+
+        client.get("/items/#{item_id}/transactions", params: params)
+      end
+
+      # List item batch transactions
+      #
+      # @param item_id [String] the item ID
+      # @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 batch transactions array
+      #
+      # @example
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.list_batch_transactions("item_id")
+      #   response.data # => {"batch_transactions" => [{"id" => "...", ...}]}
+      #
+      # @see https://developer.hellozai.com/reference/listitembatchtransactions
+      def list_batch_transactions(item_id, limit: 10, offset: 0)
+        validate_id!(item_id, 'item_id')
+
+        params = {
+          limit: limit,
+          offset: offset
+        }
+
+        client.get("/items/#{item_id}/batch_transactions", params: params)
+      end
+
+      # Show item status
+      #
+      # @param item_id [String] the item ID
+      # @return [Response] the API response containing status details
+      #
+      # @example
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.show_status("item_id")
+      #   response.data # => {"items" => {"state" => "...", ...}}
+      #
+      # @see https://developer.hellozai.com/reference/showitemstatus
+      def show_status(item_id)
+        validate_id!(item_id, 'item_id')
+        client.get("/items/#{item_id}/status")
+      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)
+        validate_required_attributes!(attributes)
+        validate_amount!(attributes[:amount]) if attributes[:amount]
+        validate_payment_type!(attributes[:payment_type]) if attributes[:payment_type]
+      end
+
+      def validate_required_attributes!(attributes)
+        required_fields = %i[name amount payment_type buyer_id seller_id]
+
+        missing_fields = required_fields.select do |field|
+          attributes[field].nil? || (attributes[field].respond_to?(:empty?) && attributes[field].to_s.strip.empty?)
+        end
+
+        return if missing_fields.empty?
+
+        raise Errors::ValidationError,
+              "Missing required fields: #{missing_fields.join(', ')}"
+      end
+
+      def validate_amount!(amount)
+        return if amount.is_a?(Integer) && amount.positive?
+
+        raise Errors::ValidationError, 'amount must be a positive integer (in cents)'
+      end
+
+      def validate_payment_type!(payment_type)
+        # Payment types: 1-7 (2 is default)
+        valid_types = %w[1 2 3 4 5 6 7]
+        return if valid_types.include?(payment_type.to_s)
+
+        raise Errors::ValidationError, 'payment_type must be between 1 and 7'
+      end
+
+      def build_item_body(attributes)
+        body = {}
+
+        attributes.each do |key, value|
+          next if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+          api_field = FIELD_MAPPING[key]
+          body[api_field] = value if api_field
+        end
+
+        body
+      end
+    end
+  end
+end

data/lib/zai_payment/resources/user.rb

@@ -107,19 +107,22 @@ module ZaiPayment
       # @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] :user_type User type ('payin' or 'payout').
+      #   This determines which fields are required.
       # @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] :address_line1 (Required for payout) user's address line 1
+      # @option attributes [String] :city (Required for payout) user's city
+      # @option attributes [String] :state (Required for payout) user's state
+      # @option attributes [String] :zip (Required for payout) user's postal/zip code
+      # @option attributes [String] :dob (Required for payout) user's date of birth (DD/MM/YYYY)
+      # @option attributes [String] :device_id device ID for fraud prevention (required when charging card)
+      # @option attributes [String] :ip_address IP address for fraud prevention (required when charging card)
+      # @option attributes [String] :address_line2 user's address line 2
       # @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
@@ -129,13 +132,12 @@ module ZaiPayment
       # @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(
+      #     user_type: "payin",
       #     email: "buyer@example.com",
       #     first_name: "John",
       #     last_name: "Doe",
@@ -146,25 +148,29 @@ module ZaiPayment
       #     state: "NY",
       #     zip: "10001"
       #   )
+      #   # Note: device_id and ip_address are not required at user creation,
+      #   # but will be required when creating an item and charging a card
       #
       # @example Create a payin user with custom ID
       #   users = ZaiPayment::Resources::User.new
       #   response = users.create(
       #     id: "buyer-#{your_user_id}",
+      #     user_type: "payin",
       #     email: "buyer@example.com",
       #     first_name: "John",
       #     last_name: "Doe",
       #     country: "USA"
       #   )
       #
-      # @example Create a payout user (seller/merchant)
+      # @example Create a payout user (seller/merchant) - individual
       #   users = ZaiPayment::Resources::User.new
       #   response = users.create(
+      #     user_type: "payout",
       #     email: "seller@example.com",
       #     first_name: "Jane",
       #     last_name: "Smith",
       #     country: "AUS",
-      #     dob: "19900101",
+      #     dob: "01/01/1990",
       #     address_line1: "456 Market St",
       #     city: "Sydney",
       #     state: "NSW",
@@ -172,13 +178,19 @@ module ZaiPayment
       #     mobile: "+61412345678"
       #   )
       #
-      # @example Create a user with company details
+      # @example Create a payout user with company details
       #   users = ZaiPayment::Resources::User.new
       #   response = users.create(
+      #     user_type: "payout",
       #     email: "business@example.com",
       #     first_name: "John",
       #     last_name: "Doe",
       #     country: "AUS",
+      #     dob: "15/06/1985",
+      #     address_line1: "789 Business Ave",
+      #     city: "Melbourne",
+      #     state: "VIC",
+      #     zip: "3000",
       #     mobile: "+61412345678",
       #     authorized_signer_title: "Director",
       #     company: {
@@ -186,13 +198,12 @@ module ZaiPayment
       #       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"
+      #       phone: "+61398765432",
+      #       country: "AUS"
       #     }
       #   )
       #
@@ -274,12 +285,23 @@ module ZaiPayment
         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]
+        validate_company!(attributes[:company], attributes[:user_type]) if attributes[:company]
       end
 
       def validate_required_attributes!(attributes)
+        # Base required fields for all users
         required_fields = %i[email first_name last_name country]
 
+        # Additional required fields for payout users
+        user_type = attributes[:user_type]&.to_s&.downcase
+        if user_type == USER_TYPE_PAYOUT
+          # For payout users, these fields become required
+          required_fields += %i[address_line1 city state zip dob]
+        end
+
+        # NOTE: device_id and ip_address are NOT required at user creation for payin users.
+        # They are only required later when an item is created and a card is charged.
+
         missing_fields = required_fields.select do |field|
           attributes[field].nil? || attributes[field].to_s.strip.empty?
         end
@@ -329,15 +351,11 @@ module ZaiPayment
         raise Errors::ValidationError, 'id cannot be blank if provided'
       end
 
-      def validate_company!(company)
+      def validate_company!(company, user_type = nil)
         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
+        required_fields = required_company_fields(user_type)
+        missing_fields = find_missing_company_fields(company, required_fields)
 
         return if missing_fields.empty?
 
@@ -345,6 +363,26 @@ module ZaiPayment
               "Company is missing required fields: #{missing_fields.join(', ')}"
       end
 
+      def required_company_fields(user_type)
+        base_fields = %i[name legal_name tax_number business_email]
+        additional_fields = payout_company?(user_type) ? payout_company_fields : %i[country]
+        base_fields + additional_fields
+      end
+
+      def payout_company?(user_type)
+        user_type&.to_s&.downcase == USER_TYPE_PAYOUT
+      end
+
+      def payout_company_fields
+        %i[address_line1 city state zip phone country]
+      end
+
+      def find_missing_company_fields(company, required_fields)
+        required_fields.select do |field|
+          company[field].nil? || company[field].to_s.strip.empty?
+        end
+      end
+
       def build_user_body(attributes) # rubocop:disable Metrics/CyclomaticComplexity
         body = {}
 

data/lib/zai_payment/response.rb

@@ -30,9 +30,14 @@ module ZaiPayment
     end
 
     # Get the data from the response body
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
     def data
-      body.is_a?(Hash) ? body['webhooks'] || body['users'] || body : body
+      return body unless body.is_a?(Hash)
+
+      body['webhooks'] || body['users'] || body['items'] || body['fees'] ||
+        body['transactions'] || body['batch_transactions'] || body
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
 
     # Get pagination or metadata info
     def meta

data/lib/zai_payment/version.rb

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

data/lib/zai_payment.rb

@@ -12,6 +12,7 @@ require_relative 'zai_payment/client'
 require_relative 'zai_payment/response'
 require_relative 'zai_payment/resources/webhook'
 require_relative 'zai_payment/resources/user'
+require_relative 'zai_payment/resources/item'
 
 module ZaiPayment
   class << self
@@ -45,5 +46,10 @@ module ZaiPayment
     def users
       @users ||= Resources::User.new(client: Client.new(base_endpoint: :core_base))
     end
+
+    # @return [ZaiPayment::Resources::Item] item resource instance
+    def items
+      @items ||= Resources::Item.new
+    end
   end
 end