abacatepay-ruby 0.1.0 → 1.0.0

data/lib/abacate_pay/clients/billing_client.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Clients
+    # Client class for managing billing-related operations in the AbacatePay API.
+    class BillingClient < Client
+      # API endpoint for billing-related operations
+      URI = "billings"
+
+      # @param client [Faraday::Connection, nil] Optional Faraday client for custom configurations
+      # @deprecated Use {CheckoutClient} instead
+      def initialize(client = nil)
+        warn "[DEPRECATION] BillingClient is deprecated. Use CheckoutClient instead."
+        super(URI, client)
+      end
+
+      # Retrieves a list of billings
+      #
+      # @return [Array<Resources::Billing>] Array of Billing objects
+      def list
+        response = request("GET", "list")
+        Array(response).map { |data| Resources::Billings.new(data) }
+      end
+
+      # Creates a new billing
+      #
+      # @param data [Resources::Billing] The billing data to be sent for creation
+      # @return [Resources::Billing] The created Billing object
+      def create(data)
+        response = request("POST", "create", json: build_create_payload(data))
+        Resources::Billings.new(response)
+      end
+
+      private
+
+      # Builds the create-billing request payload
+      #
+      # @param data [Resources::Billings] The billing to serialize
+      # @return [Hash] The request payload
+      def build_create_payload(data)
+        {
+          frequency: data.frequency,
+          methods: data.methods,
+          returnUrl: data.metadata&.return_url,
+          completionUrl: data.metadata&.completion_url,
+          items: data.products&.map { |product| serialize_product(product) }
+        }.merge(serialize_customer(data.customer))
+      end
+
+      # @param product [Resources::Billings::Product] The product to serialize
+      # @return [Hash] The product payload
+      def serialize_product(product)
+        {
+          externalId: product.external_id,
+          name: product.name,
+          description: product.description,
+          quantity: product.quantity,
+          price: product.price
+        }
+      end
+
+      # An existing customer is referenced by id; a new one is sent inline.
+      #
+      # @param customer [Resources::Customers, nil] The customer to serialize
+      # @return [Hash] The customer payload fragment
+      def serialize_customer(customer)
+        return { customerId: customer.id } if customer&.id
+
+        {
+          customer: {
+            name: customer&.metadata&.name,
+            email: customer&.metadata&.email,
+            cellphone: customer&.metadata&.cellphone,
+            taxId: customer&.metadata&.tax_id
+          }
+        }
+      end
+    end
+  end
+end

data/lib/abacate_pay/clients/checkout_client.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Clients
+    # Client for one-off checkout sessions in the AbacatePay API.
+    #
+    # Checkouts are single-payment links; use SubscriptionClient for
+    # recurring charges.
+    class CheckoutClient < Client
+      URI = "checkouts"
+
+      def initialize(client = nil)
+        super(URI, client)
+      end
+
+      # @param params [Hash] Optional filtering params (id, externalId, status, email, taxId, after, before, limit)
+      # @return [Array<Resources::Checkouts>]
+      def list(**params)
+        response = request("GET", "list", params: params.empty? ? nil : params)
+        Array(response).map { |data| Resources::Checkouts.new(data) }
+      end
+
+      # @param id [String] Checkout ID
+      # @return [Resources::Checkouts]
+      def get(id)
+        response = request("GET", "get", params: { id: id })
+        Resources::Checkouts.new(response)
+      end
+
+      # @param data [Resources::Checkouts]
+      # @return [Resources::Checkouts]
+      def create(data)
+        response = request("POST", "create", json: build_create_payload(data))
+        Resources::Checkouts.new(response)
+      end
+
+      # Refunds a paid checkout in full. AbacatePay does not support partial
+      # refunds — the original amount is always returned.
+      #
+      # @param id [String] Public checkout ID (`bill_...`) or charge ID
+      #   (`char_...`, `pix_char_...`, `card_...`)
+      # @return [Resources::Checkouts] The refunded checkout
+      def refund(id)
+        response = request("POST", "refund", json: { id: id })
+        Resources::Checkouts.new(response)
+      end
+
+      private
+
+      # Builds the create-checkout request payload
+      #
+      # @param data [Resources::Checkouts] The checkout to serialize
+      # @return [Hash] The request payload, with nil entries removed
+      def build_create_payload(data)
+        customer_id = data.customer&.id
+
+        {
+          frequency: data.frequency,
+          methods: data.methods,
+          returnUrl: data.metadata&.return_url,
+          completionUrl: data.metadata&.completion_url,
+          items: data.products&.map { |product| { id: product.external_id, quantity: product.quantity } },
+          externalId: data.external_id,
+          coupons: data.coupons,
+          customerId: customer_id.to_s.empty? ? nil : customer_id
+        }.compact
+      end
+    end
+  end
+end

data/lib/{abacatepay → abacate_pay}/clients/client.rb

@@ -27,10 +27,14 @@ module AbacatePay
       def request(method, uri, options = {})
         response = @client.public_send(method.downcase) do |req|
           req.url uri
+          req.params = options[:params] if options[:params]
           req.body = options[:json].to_json if options[:json]
         end
 
-        JSON.parse(response.body).fetch("data")
+        parsed = JSON.parse(response.body)
+        raise ApiError, "API error: #{parsed["error"]}" if parsed["error"]
+
+        parsed.fetch("data")
       rescue Faraday::Error => e
         handle_request_error(e)
       rescue StandardError => e
@@ -42,11 +46,20 @@ module AbacatePay
       # @param uri [String] The endpoint URI
       # @return [Faraday::Connection] Configured Faraday client
       def build_client(uri)
+        configuration = AbacatePay.configuration!
+        base_url = uri.empty? ? "#{configuration.api_url}/" : "#{configuration.api_url}/#{uri}/"
+
         Faraday.new(
-          url: "#{AbacatePay.configuration.api_url}/#{uri}/",
+          url: base_url,
           headers: {
             "Content-Type" => "application/json",
-            "Authorization" => "Bearer #{AbacatePay.configuration.api_token}"
+            "Authorization" => "Bearer #{configuration.api_token}"
+          },
+          # Without an explicit timeout a hung gateway blocks the caller's
+          # thread indefinitely — inside a Rails request, that is an outage.
+          request: {
+            timeout: configuration.timeout,
+            open_timeout: configuration.timeout
           }
         )
       end
@@ -57,12 +70,12 @@ module AbacatePay
       # @raise [ApiError] With appropriate error message
       def handle_request_error(error)
         error_message = if error.response&.body
-          response_body = JSON.parse(error.response.body)
-          response_body["message"] || response_body["error"]
-        end
+                          response_body = JSON.parse(error.response.body)
+                          response_body["message"] || response_body["error"]
+                        end
 
         raise ApiError, "Request error: #{error_message || error.message}"
       end
     end
   end
-end
+end

data/lib/abacate_pay/clients/coupon_client.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Clients
+    # Client for discount coupons in the AbacatePay API.
+    #
+    # Supports creating, listing, deleting and toggling coupons
+    # between active and inactive.
+    class CouponClient < Client
+      URI = "coupons"
+
+      def initialize(client = nil)
+        super(URI, client)
+      end
+
+      # @param params [Hash] Optional pagination params (after, before, limit)
+      # @return [Array<Resources::Coupons>]
+      def list(**params)
+        response = request("GET", "list", params: params.empty? ? nil : params)
+        Array(response).map { |data| Resources::Coupons.new(data) }
+      end
+
+      # @param id [String] Coupon ID
+      # @return [Resources::Coupons]
+      def get(id)
+        response = request("GET", "get", params: { id: id })
+        Resources::Coupons.new(response)
+      end
+
+      # @param data [Resources::Coupons]
+      # @return [Resources::Coupons]
+      def create(data)
+        response = request("POST", "create", json: {
+                             code: data.code,
+                             discount: data.discount,
+                             discountKind: data.discount_kind,
+                             maxRedeems: data.max_redeems
+                           })
+        Resources::Coupons.new(response)
+      end
+
+      # @param id [String] Coupon ID
+      # @return [Resources::Coupons]
+      def delete(id)
+        response = request("POST", "delete", json: { id: id })
+        Resources::Coupons.new(response)
+      end
+
+      # @param id [String] Coupon ID
+      # @return [Resources::Coupons]
+      def toggle(id)
+        response = request("POST", "toggle", json: { id: id })
+        Resources::Coupons.new(response)
+      end
+    end
+  end
+end

data/lib/abacate_pay/clients/customer_client.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Clients
+    # Client class for managing customer-related operations in the AbacatePay API.
+    class CustomerClient < Client
+      # API endpoint for customer-related operations
+      URI = "customers"
+
+      # @param client [Faraday::Connection, nil] Optional Faraday client for custom configurations
+      def initialize(client = nil)
+        super(URI, client)
+      end
+
+      # Retrieves a list of customers
+      #
+      # @param params [Hash] Optional pagination params (after, before, limit)
+      # @return [Array<Resources::Customers>] Array of Customer objects
+      def list(**params)
+        response = request("GET", "list", params: params.empty? ? nil : params)
+        Array(response).map { |data| Resources::Customers.new(data) }
+      end
+
+      # Retrieves a customer by ID
+      #
+      # @param id [String] The customer ID
+      # @return [Resources::Customers] The Customer object
+      def get(id)
+        response = request("GET", "get", params: { id: id })
+        Resources::Customers.new(response)
+      end
+
+      # Creates a new customer
+      #
+      # @param data [Resources::Customers] The customer data to be sent for creation
+      # @return [Resources::Customers] The created Customer object
+      def create(data)
+        response = request("POST", "create", json: {
+                             name: data.metadata&.name,
+                             email: data.metadata&.email,
+                             cellphone: data.metadata&.cellphone,
+                             taxId: data.metadata&.tax_id
+                           })
+
+        Resources::Customers.new(response)
+      end
+
+      # Deletes a customer
+      #
+      # @param id [String] The customer ID
+      # @return [Resources::Customers] The deleted Customer object
+      def delete(id)
+        response = request("POST", "delete", json: { id: id })
+        Resources::Customers.new(response)
+      end
+    end
+  end
+end

data/lib/abacate_pay/clients/payment_link_client.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Clients
+    # Client for reusable payment links in the AbacatePay API.
+    #
+    # A payment link can be paid by many customers independently — mass sales,
+    # raffles, sign-up forms — without creating one checkout per customer.
+    # Use CheckoutClient when each customer needs their own charge.
+    class PaymentLinkClient < Client
+      URI = "payment-links"
+
+      # Payment links are always multi-payment by definition; the API rejects
+      # any other frequency on this endpoint.
+      FREQUENCY = "MULTIPLE_PAYMENTS"
+
+      # @param client [Faraday::Connection, nil] Optional Faraday client
+      def initialize(client = nil)
+        super(URI, client)
+      end
+
+      # @param params [Hash] Optional pagination params (after, before, limit)
+      # @return [Array<Resources::Checkouts>]
+      def list(**params)
+        response = request("GET", "list", params: params.empty? ? nil : params)
+        Array(response).map { |data| Resources::Checkouts.new(data) }
+      end
+
+      # @param id [String] The payment link ID
+      # @return [Resources::Checkouts]
+      def get(id)
+        response = request("GET", "get", params: { id: id })
+        Resources::Checkouts.new(response)
+      end
+
+      # Creates a reusable payment link.
+      #
+      # @param data [Resources::Checkouts] The link definition
+      # @return [Resources::Checkouts] The created link, with `url` populated
+      def create(data)
+        response = request("POST", "create", json: build_create_payload(data))
+        Resources::Checkouts.new(response)
+      end
+
+      # Refunds a payment made through the link.
+      #
+      # @param id [String] Public charge ID
+      # @return [Resources::Checkouts] The refunded charge
+      def refund(id)
+        response = request("POST", "refund", json: { id: id })
+        Resources::Checkouts.new(response)
+      end
+
+      private
+
+      # @param data [Resources::Checkouts] The link to serialize
+      # @return [Hash] The request payload, with nil entries removed
+      def build_create_payload(data)
+        {
+          frequency: FREQUENCY,
+          methods: data.methods,
+          items: data.products&.map { |product| { id: product.external_id, quantity: product.quantity } },
+          externalId: data.external_id,
+          returnUrl: data.metadata&.return_url,
+          completionUrl: data.metadata&.completion_url,
+          coupons: data.coupons
+        }.compact
+      end
+    end
+  end
+end

data/lib/abacate_pay/clients/payout_client.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Clients
+    # Client for payouts (withdrawals) in the AbacatePay API.
+    #
+    # Payouts move settled balance out of the store account.
+    class PayoutClient < Client
+      URI = "payouts"
+
+      def initialize(client = nil)
+        super(URI, client)
+      end
+
+      # @param params [Hash] Optional pagination params (after, before, limit)
+      # @return [Array<Resources::Payouts>]
+      def list(**params)
+        response = request("GET", "list", params: params.empty? ? nil : params)
+        Array(response).map { |data| Resources::Payouts.new(data) }
+      end
+
+      # @param id [String] Payout ID
+      # @return [Resources::Payouts]
+      def get(id)
+        response = request("GET", "get", params: { id: id })
+        Resources::Payouts.new(response)
+      end
+
+      # @param data [Resources::Payouts]
+      # @return [Resources::Payouts]
+      def create(data)
+        response = request("POST", "create", json: {
+                             amount: data.amount,
+                             externalId: data.external_id,
+                             description: data.description
+                           })
+        Resources::Payouts.new(response)
+      end
+    end
+  end
+end

data/lib/abacate_pay/clients/pix_client.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Clients
+    # Client for outbound PIX transfers in the AbacatePay API.
+    #
+    # Transfers are sent to a PIX key; see Enums::Pix::KeyTypes for the
+    # accepted key formats.
+    class PixClient < Client
+      URI = "pix"
+
+      def initialize(client = nil)
+        super(URI, client)
+      end
+
+      # @param params [Hash] Optional pagination params (after, before, limit)
+      # @return [Array<Resources::PixTransfers>]
+      def list(**params)
+        response = request("GET", "list", params: params.empty? ? nil : params)
+        Array(response).map { |data| Resources::PixTransfers.new(data) }
+      end
+
+      # @param id [String] PIX transfer ID
+      # @return [Resources::PixTransfers]
+      def get(id)
+        response = request("GET", "get", params: { id: id })
+        Resources::PixTransfers.new(response)
+      end
+
+      # Sends a PIX transfer to an external key.
+      # Named send_pix to avoid conflict with Ruby's Object#send.
+      #
+      # @param data [Resources::PixTransfers]
+      # @return [Resources::PixTransfers]
+      def send_pix(data)
+        response = request("POST", "send", json: {
+                             amount: data.amount,
+                             externalId: data.external_id,
+                             description: data.description,
+                             key: data.key,
+                             keyType: data.key_type
+                           })
+        Resources::PixTransfers.new(response)
+      end
+    end
+  end
+end

data/lib/abacate_pay/clients/product_client.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Clients
+    # Client for the product catalogue in the AbacatePay API.
+    #
+    # Products are the line items referenced by billings and checkouts.
+    class ProductClient < Client
+      URI = "products"
+
+      def initialize(client = nil)
+        super(URI, client)
+      end
+
+      # @param params [Hash] Optional pagination params (after, before, limit)
+      # @return [Array<Resources::Products>]
+      def list(**params)
+        response = request("GET", "list", params: params.empty? ? nil : params)
+        Array(response).map { |data| Resources::Products.new(data) }
+      end
+
+      # @param id [String] Product ID or externalId
+      # @return [Resources::Products]
+      def get(id)
+        response = request("GET", "get", params: { id: id })
+        Resources::Products.new(response)
+      end
+
+      # @param data [Resources::Products]
+      # @return [Resources::Products]
+      def create(data)
+        request_data = {
+          externalId: data.external_id,
+          name: data.name,
+          price: data.price,
+          currency: data.currency || "BRL",
+          description: data.description
+        }
+        request_data[:imageUrl] = data.image_url if data.image_url && !data.image_url.to_s.empty?
+        request_data[:cycle] = data.cycle if data.cycle && !data.cycle.to_s.empty?
+
+        response = request("POST", "create", json: request_data)
+        Resources::Products.new(response)
+      end
+
+      # @param id [String] Product ID
+      # @return [Resources::Products]
+      def delete(id)
+        response = request("POST", "delete", json: { id: id })
+        Resources::Products.new(response)
+      end
+    end
+  end
+end

data/lib/abacate_pay/clients/store_client.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Clients
+    # Client for store-level data in the AbacatePay API.
+    #
+    # Exposes the account balance and revenue reporting for a date range.
+    class StoreClient < Client
+      def initialize(client = nil)
+        super("", client)
+      end
+
+      # @return [Resources::Store]
+      def get
+        response = request("GET", "store/get")
+        Resources::Store.new(response)
+      end
+
+      # @return [Hash] Merchant info
+      def merchant_info
+        request("GET", "public-mrr/merchant-info")
+      end
+
+      # @return [Hash] MRR metrics
+      def mrr
+        request("GET", "public-mrr/mrr")
+      end
+
+      # @param start_date [String] Start date (YYYY-MM-DD)
+      # @param end_date [String] End date (YYYY-MM-DD)
+      # @return [Hash] Revenue data
+      def revenue(start_date:, end_date:)
+        request("GET", "public-mrr/revenue", params: {
+                  startDate: start_date,
+                  endDate: end_date
+                })
+      end
+    end
+  end
+end

data/lib/abacate_pay/clients/subscription_client.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Clients
+    # Client for recurring subscriptions in the AbacatePay API.
+    #
+    # See Enums::Products::Cycles for the supported billing cycles.
+    class SubscriptionClient < Client
+      URI = "subscriptions"
+
+      def initialize(client = nil)
+        super(URI, client)
+      end
+
+      # @param params [Hash] Optional pagination params (after, before, limit)
+      # @return [Array<Resources::Subscriptions>]
+      def list(**params)
+        response = request("GET", "list", params: params.empty? ? nil : params)
+        Array(response).map { |data| Resources::Subscriptions.new(data) }
+      end
+
+      # @param data [Resources::Subscriptions]
+      # @return [Resources::Subscriptions]
+      def create(data)
+        request_data = {
+          methods: data.methods,
+          externalId: data.external_id,
+          customerId: data.customer&.id,
+          items: data.products&.map do |product|
+            {
+              externalId: product.external_id,
+              name: product.name,
+              description: product.description,
+              quantity: product.quantity,
+              price: product.price
+            }
+          end
+        }
+
+        response = request("POST", "create", json: request_data)
+        Resources::Subscriptions.new(response)
+      end
+
+      # Cancels an active subscription immediately. Pending future instalments
+      # are cancelled along with it.
+      #
+      # @param id [String] The subscription ID (`subs_...`)
+      # @return [Resources::Subscriptions] The cancelled subscription
+      def cancel(id)
+        response = request("POST", "cancel", json: { id: id })
+        Resources::Subscriptions.new(response)
+      end
+    end
+  end
+end