lago-ruby-client 1.45.0 → 1.47.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b15e8ca518f9d0d1d09afc59ccd0c89088b37b1e77814f829d3f3e1db9bc032
-  data.tar.gz: f43d20d1636ef1657e78224b9f9f505d88708762f540d21c3c8051eea26637fc
+  metadata.gz: f1ce7eaf525a2785545ea91a30464c1da9da45a09c95d01a6b062cd4b51a85f5
+  data.tar.gz: 6d8be436f3b5b4155d8e72e28aea99082fd40dfa1070a18758e40842ede13d34
 SHA512:
-  metadata.gz: 4d3fb72ab5775cd0dc7368ef4c7b7977b3f2d461f3e1707e9c165580eabfc33c38f1d12668071eaae8aa870cc5461dbd60e6202d46d8450d6092b77882ed7a9b
-  data.tar.gz: 56eb3276e804169e4dd1b7bfbaf1685d19c9a747fdb658204082f39faef5c00bff852ca3f7bb90c5e0a2d8c2ebb4e3361b176af9ac97a0cdffe9c66d6ff80cb7
+  metadata.gz: c10616c41e59442007247c9245bb91be08881744dbf91f9112dbe4043e7d19c33539aa50c8367f77a06a6d3fd49efa5d5a3add3f10842eaa05cc0d0ab0f2643d
+  data.tar.gz: adc378ba5f462f08880bbd3ff8b841b9432660a378f3dec36aeab4b4065e0ecaf07608a27ead50a49cea6eab701c250e0f2e89915d1d13df016f22c252dc95de

data/lib/lago/api/client.rb

@@ -53,13 +53,22 @@ module Lago
     API_PATH = 'api/v1/'
 
     class Client
-      attr_reader :api_key, :api_url, :use_ingest_service, :ingest_api_url
-
-      def initialize(api_key: nil, api_url: nil, use_ingest_service: false, ingest_api_url: nil)
+      attr_reader :api_key,
+                  :api_url,
+                  :use_ingest_service,
+                  :ingest_api_url,
+                  :max_retries,
+                  :retry_on_rate_limit,
+                  :on_rate_limit_info
+
+      def initialize(api_key: nil, api_url: nil, use_ingest_service: false, ingest_api_url: nil, **options)
         @api_key = api_key
         @api_url = api_url
         @use_ingest_service = use_ingest_service
         @ingest_api_url = ingest_api_url
+        @max_retries = options.fetch(:max_retries, 3)
+        @retry_on_rate_limit = options.fetch(:retry_on_rate_limit, true)
+        @on_rate_limit_info = options[:on_rate_limit_info]
       end
 
       def base_api_url

data/lib/lago/api/connection.rb

@@ -6,84 +6,73 @@ module Lago
   module Api
     class Connection
       RESPONSE_SUCCESS_CODES = [200, 201, 202, 204].freeze
-
-      def initialize(api_key, uri)
+      DEFAULT_MAX_RETRIES = 3
+      INITIAL_BACKOFF = 1
+      BACKOFF_MULTIPLIER = 2
+      MAX_RETRY_DELAY = 20
+
+      def initialize(
+        api_key,
+        uri,
+        max_retries: DEFAULT_MAX_RETRIES,
+        retry_on_rate_limit: true,
+        on_rate_limit_info: nil
+      )
         @api_key = api_key
         @uri = uri
+        @max_retries = max_retries
+        @retry_on_rate_limit = retry_on_rate_limit
+        @on_rate_limit_info = on_rate_limit_info
       end
 
       def post(body, path = uri.path)
-        response = http_client.send_request(
-          'POST',
-          path,
-          prepare_payload(body),
-          headers
-        )
-
-        handle_response(response)
+        method = 'POST'
+        execute_request(method:) do
+          http_client.send_request(method, path, prepare_payload(body), headers)
+        end
       end
 
       def put(path = uri.path, identifier:, body:)
+        method = 'PUT'
         uri_path = identifier.nil? ? path : "#{path}/#{CGI.escapeURIComponent(identifier)}"
-        response = http_client.send_request(
-          'PUT',
-          uri_path,
-          prepare_payload(body),
-          headers
-        )
-
-        handle_response(response)
+        execute_request(method:) do
+          http_client.send_request(method, uri_path, prepare_payload(body), headers)
+        end
       end
 
       def patch(path = uri.path, identifier:, body:)
+        method = 'PATCH'
         uri_path = identifier.nil? ? path : "#{path}/#{CGI.escapeURIComponent(identifier)}"
-        response = http_client.send_request(
-          'PATCH',
-          uri_path,
-          prepare_payload(body),
-          headers
-        )
-
-        handle_response(response)
+        execute_request(method:) do
+          http_client.send_request(method, uri_path, prepare_payload(body), headers)
+        end
       end
 
       def get(path = uri.path, identifier:)
+        method = 'GET'
         uri_path = identifier.nil? ? path : "#{path}/#{CGI.escapeURIComponent(identifier)}"
-        response = http_client.send_request(
-          'GET',
-          uri_path,
-          prepare_payload(nil),
-          headers
-        )
-
-        handle_response(response)
+        execute_request(method:) do
+          http_client.send_request(method, uri_path, prepare_payload(nil), headers)
+        end
       end
 
       def destroy(path = uri.path, identifier:, options: nil)
+        method = 'DELETE'
         uri_path = path
         uri_path += "/#{CGI.escapeURIComponent(identifier)}" if identifier
         uri_path += "?#{URI.encode_www_form(options)}" unless options.nil?
-        response = http_client.send_request(
-          'DELETE',
-          uri_path,
-          prepare_payload(nil),
-          headers
-        )
-
-        handle_response(response)
+        execute_request(method:) do
+          http_client.send_request(method, uri_path, prepare_payload(nil), headers)
+        end
       end
 
       def get_all(options, path = uri.path)
+        method = 'GET'
         uri_path = options.empty? ? path : "#{path}?#{URI.encode_www_form(options)}"
 
-        response = http_client.send_request(
-          'GET',
-          uri_path,
-          prepare_payload(nil),
-          headers
-        )
-
-        handle_response(response)
+        execute_request(method:) do
+          http_client.send_request(method, uri_path, prepare_payload(nil), headers)
+        end
       end
 
       private
@@ -98,14 +87,47 @@ module Lago
         }
       end
 
-      def handle_response(response)
-        raise_error(response) unless RESPONSE_SUCCESS_CODES.include?(response.code.to_i)
+      def execute_request(retry_count = 0, method: nil, &block)
+        response = yield
+        handle_response(response, retry_count, block, method:)
+      end
 
-        response.body.empty? || JSON.parse(response.body)
+      def handle_response(response, retry_count, block, method: nil)
+        code = response.code.to_i
+
+        if code == 429 && @retry_on_rate_limit && retry_count < @max_retries
+          handle_rate_limit(response, retry_count, block, method:)
+        elsif !RESPONSE_SUCCESS_CODES.include?(code)
+          raise_error(response)
+        else
+          emit_rate_limit_info(response, method:)
+          parse_response_body(response)
+        end
       rescue JSON::ParserError
         response.body
       end
 
+      def handle_rate_limit(response, retry_count, block, method: nil)
+        reset_seconds = extract_reset_seconds(response, retry_count)
+        sleep(reset_seconds)
+        execute_request(retry_count + 1, method:, &block)
+      end
+
+      def emit_rate_limit_info(response, method: nil)
+        return if @on_rate_limit_info.nil?
+
+        info = Lago::Api::RateLimitInfo.parse(response, method:, url: uri.to_s)
+        return if info.nil?
+
+        @on_rate_limit_info.call(info)
+      rescue StandardError => e
+        warn("Lago: on_rate_limit_info callback raised: #{e.class}: #{e.message}")
+      end
+
+      def parse_response_body(response)
+        response.body.empty? || JSON.parse(response.body)
+      end
+
       def http_client
         http_client = Net::HTTP.new(uri.hostname, uri.port)
         http_client.use_ssl = true if uri.scheme == 'https'
@@ -120,7 +142,42 @@ module Lago
       end
 
       def raise_error(response)
-        raise Lago::Api::HttpError.new(response.code.to_i, response.body, uri)
+        code = response.code.to_i
+
+        raise Lago::Api::HttpError.new(code, response.body, uri) unless code == 429
+
+        limit, remaining, reset = parse_rate_limit_headers(response)
+        raise Lago::Api::RateLimitError.new(
+          code,
+          response.body,
+          uri,
+          limit:,
+          remaining:,
+          reset:
+        )
+      end
+
+      def parse_rate_limit_headers(response)
+        limit = response['x-ratelimit-limit']&.to_i
+        remaining = response['x-ratelimit-remaining']&.to_i
+        reset = response['x-ratelimit-reset']&.to_i
+
+        [limit, remaining, reset]
+      end
+
+      def extract_reset_seconds(response, retry_count)
+        delay = if response['x-ratelimit-reset']
+          [response['x-ratelimit-reset'].to_i, INITIAL_BACKOFF].max
+        else
+          # Exponential backoff if header is missing
+          calculate_backoff(retry_count)
+        end
+
+        [delay, MAX_RETRY_DELAY].min
+      end
+
+      def calculate_backoff(retry_count)
+        INITIAL_BACKOFF * (BACKOFF_MULTIPLIER**retry_count)
       end
     end
   end

data/lib/lago/api/logging_rate_limit_observer.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Lago
+  module Api
+    # Ready-to-use +on_rate_limit_info+ callable that logs a warning each time
+    # rate limit usage crosses one of the configured thresholds.
+    #
+    # Example:
+    #   client = Lago::Api::Client.new(
+    #     api_key: '...',
+    #     on_rate_limit_info: Lago::Api::LoggingRateLimitObserver.new,
+    #   )
+    class LoggingRateLimitObserver
+      DEFAULT_THRESHOLDS = [0.80, 0.90, 0.95].freeze
+
+      def initialize(thresholds: DEFAULT_THRESHOLDS, logger: nil, level: Logger::WARN)
+        @thresholds = thresholds.sort.reverse
+        @logger = logger || default_logger
+        @level = level
+      end
+
+      def call(info)
+        pct = info.usage_pct
+        return if pct.nil?
+
+        return unless @thresholds.any? { |threshold| pct >= threshold }
+
+        @logger.add(
+          @level,
+          format(
+            'Lago rate limit at %<pct>.0f%% (limit=%<limit>s, remaining=%<remaining>s, ' \
+            'reset=%<reset>ss, %<method>s %<url>s)',
+            pct: pct * 100,
+            limit: info.limit.inspect,
+            remaining: info.remaining.inspect,
+            reset: info.reset.inspect,
+            method: info.method,
+            url: info.url,
+          ),
+        )
+      end
+
+      private
+
+      def default_logger
+        logger = Logger.new($stderr)
+        logger.progname = 'lago_ruby_client.rate_limit'
+        logger
+      end
+    end
+  end
+end

data/lib/lago/api/rate_limit_error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Lago
+  module Api
+    class RateLimitError < HttpError
+      attr_reader :limit, :remaining, :reset
+
+      def initialize(code, body, uri, **options)
+        super(code, body, uri)
+        @limit = options[:limit]
+        @remaining = options[:remaining]
+        @reset = options[:reset]
+      end
+
+      def message
+        base_message = "HTTP #{error_code} - URI: #{uri}.\nError: #{error_body}"
+        return base_message unless reset
+
+        "#{base_message}\nRate limit will reset in #{reset} seconds."
+      end
+    end
+  end
+end

data/lib/lago/api/rate_limit_info.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Lago
+  module Api
+    # Parsed rate limit headers from a Lago API response.
+    #
+    # Delivered to the +on_rate_limit_info+ callback after every successful
+    # request so callers can build observability around the rate limit
+    # (warn at thresholds, emit metrics, etc.).
+    class RateLimitInfo
+      attr_reader :limit, :remaining, :reset, :method, :url
+
+      # Parses x-ratelimit-* headers from a Net::HTTPResponse-like object.
+      # Returns +nil+ when no rate limit headers are present.
+      def self.parse(response, method:, url:)
+        limit = response['x-ratelimit-limit']
+        remaining = response['x-ratelimit-remaining']
+        reset = response['x-ratelimit-reset']
+
+        return nil if limit.nil? && remaining.nil? && reset.nil?
+
+        new(
+          limit: limit&.to_i,
+          remaining: remaining&.to_i,
+          reset: reset&.to_i,
+          method:,
+          url:,
+        )
+      end
+
+      def initialize(limit:, remaining:, reset:, method:, url:)
+        @limit = limit
+        @remaining = remaining
+        @reset = reset
+        @method = method
+        @url = url
+      end
+
+      # Returns the fraction of the rate limit currently used as a Float in
+      # [0.0, 1.0], or +nil+ when the headers aren't usable (missing limit,
+      # zero limit, missing remaining).
+      def usage_pct
+        return nil if limit.nil? || remaining.nil? || limit.to_i <= 0
+
+        1.0 - (remaining.to_f / limit)
+      end
+    end
+  end
+end

data/lib/lago/api/resources/base.rb

@@ -59,7 +59,13 @@ module Lago
         def connection
           uri = URI.join(client.base_api_url, api_resource)
 
-          Lago::Api::Connection.new(client.api_key, uri)
+          Lago::Api::Connection.new(
+            client.api_key,
+            uri,
+            max_retries: client.max_retries,
+            retry_on_rate_limit: client.retry_on_rate_limit,
+            on_rate_limit_info: client.on_rate_limit_info,
+          )
         end
       end
     end

data/lib/lago/api/resources/customer.rb

@@ -20,10 +20,15 @@ module Lago
 
         def current_usage( # rubocop:disable Metrics/ParameterLists
           external_customer_id, external_subscription_id, apply_taxes: nil,
+          charge_id: nil, charge_code: nil, billable_metric_code: nil, group: nil,
           filter_by_charge_id: nil, filter_by_charge_code: nil, filter_by_group: nil, full_usage: nil
         )
           query_params = { external_subscription_id: external_subscription_id }
           query_params[:apply_taxes] = apply_taxes unless apply_taxes.nil?
+          query_params[:charge_id] = charge_id unless charge_id.nil?
+          query_params[:charge_code] = charge_code unless charge_code.nil?
+          query_params[:billable_metric_code] = billable_metric_code unless billable_metric_code.nil?
+          group&.each { |k, v| query_params[:"group[#{k}]"] = v }
           query_params[:filter_by_charge_id] = filter_by_charge_id unless filter_by_charge_id.nil?
           query_params[:filter_by_charge_code] = filter_by_charge_code unless filter_by_charge_code.nil?
           filter_by_group&.each { |k, v| query_params[:"filter_by_group[#{k}]"] = v }

data/lib/lago/api/resources/event.rb

@@ -16,7 +16,13 @@ module Lago
 
         def create(params)
           uri = URI("#{client.base_ingest_api_url}#{api_resource}")
-          connection = Lago::Api::Connection.new(client.api_key, uri)
+          connection = Lago::Api::Connection.new(
+            client.api_key,
+            uri,
+            max_retries: client.max_retries,
+            retry_on_rate_limit: client.retry_on_rate_limit,
+            on_rate_limit_info: client.on_rate_limit_info,
+          )
 
           payload = whitelist_params(params)
           response = connection.post(payload, uri)[root_name]

data/lib/lago/api/resources/nested.rb

@@ -8,7 +8,13 @@ module Lago
       class Nested < Base
         def initialize(client)
           super(client)
-          @connection = Lago::Api::Connection.new(client.api_key, client.base_api_url)
+          @connection = Lago::Api::Connection.new(
+            client.api_key,
+            client.base_api_url,
+            max_retries: client.max_retries,
+            retry_on_rate_limit: client.retry_on_rate_limit,
+            on_rate_limit_info: client.on_rate_limit_info,
+          )
         end
 
         def create(*parent_ids, params)

data/lib/lago/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Lago
-  VERSION = '1.45.0'
+  VERSION = '1.47.0'
 end

data/lib/lago-ruby-client.rb

@@ -11,3 +11,6 @@ require 'lago/version'
 require 'lago/api/client'
 require 'lago/api/connection'
 require 'lago/api/http_error'
+require 'lago/api/rate_limit_error'
+require 'lago/api/rate_limit_info'
+require 'lago/api/logging_rate_limit_observer'

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: lago-ruby-client
 version: !ruby/object:Gem::Version
-  version: 1.45.0
+  version: 1.47.0
 platform: ruby
 authors:
 - Lovro Colic
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jwt
@@ -52,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: benchmark
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bigdecimal
   requirement: !ruby/object:Gem::Requirement
@@ -192,6 +205,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: readline
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -276,7 +303,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
 email:
 - lovro@getlago.com
 executables: []
@@ -287,6 +313,9 @@ files:
 - lib/lago/api/client.rb
 - lib/lago/api/connection.rb
 - lib/lago/api/http_error.rb
+- lib/lago/api/logging_rate_limit_observer.rb
+- lib/lago/api/rate_limit_error.rb
+- lib/lago/api/rate_limit_info.rb
 - lib/lago/api/resources/activity_log.rb
 - lib/lago/api/resources/add_on.rb
 - lib/lago/api/resources/api_log.rb
@@ -341,7 +370,6 @@ metadata:
   homepage_uri: https://www.getlago.com/
   source_code_uri: https://github.com/getlago/lago-ruby-client
   documentation_uri: https://doc.getlago.com
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -356,8 +384,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.27
-signing_key:
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Lago Rest API client
 test_files: []