lago-ruby-client 1.46.0 → 1.47.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0d737a1ba08ae4f9d2a731af4cf55918555cfe91e1606fbef6126b830090e82
-  data.tar.gz: 06b6d2a32667abe5872075cb96081aedff4d0d07fa49e0a4158f594ee66f4803
+  metadata.gz: f1ce7eaf525a2785545ea91a30464c1da9da45a09c95d01a6b062cd4b51a85f5
+  data.tar.gz: 6d8be436f3b5b4155d8e72e28aea99082fd40dfa1070a18758e40842ede13d34
 SHA512:
-  metadata.gz: fbb748d95cb04580ecba3e5340e5587c72f4b20ce629fefc06eeb8435c074cbde11e8874407bcdf3f0f32680e961ca553b1b6ae929d695357e2bf2d21ca13041
-  data.tar.gz: a0ef70eeb95aff16cef4492c9b2ba989323b7bae8cbc26b50a9cb3e098cd49ea54bee30fc83e6f4912f226eb5bfb538a3bb3e3f3c6829ec592b2e50bee474778
+  metadata.gz: c10616c41e59442007247c9245bb91be08881744dbf91f9112dbe4043e7d19c33539aa50c8367f77a06a6d3fd49efa5d5a3add3f10842eaa05cc0d0ab0f2643d
+  data.tar.gz: adc378ba5f462f08880bbd3ff8b841b9432660a378f3dec36aeab4b4065e0ecaf07608a27ead50a49cea6eab701c250e0f2e89915d1d13df016f22c252dc95de

data/lib/lago/api/client.rb

@@ -53,7 +53,13 @@ module Lago
     API_PATH = 'api/v1/'
 
     class Client
-      attr_reader :api_key, :api_url, :use_ingest_service, :ingest_api_url, :max_retries, :retry_on_rate_limit
+      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
@@ -62,6 +68,7 @@ module Lago
         @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

@@ -11,84 +11,67 @@ module Lago
       BACKOFF_MULTIPLIER = 2
       MAX_RETRY_DELAY = 20
 
-      def initialize(api_key, uri, max_retries: DEFAULT_MAX_RETRIES, retry_on_rate_limit: true)
+      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)
-        execute_request do
-          http_client.send_request(
-            'POST',
-            path,
-            prepare_payload(body),
-            headers
-          )
+        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)}"
-        execute_request do
-          http_client.send_request(
-            'PUT',
-            uri_path,
-            prepare_payload(body),
-            headers
-          )
+        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)}"
-        execute_request do
-          http_client.send_request(
-            'PATCH',
-            uri_path,
-            prepare_payload(body),
-            headers
-          )
+        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)}"
-        execute_request do
-          http_client.send_request(
-            'GET',
-            uri_path,
-            prepare_payload(nil),
-            headers
-          )
+        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?
-        execute_request do
-          http_client.send_request(
-            'DELETE',
-            uri_path,
-            prepare_payload(nil),
-            headers
-          )
+        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)}"
 
-        execute_request do
-          http_client.send_request(
-            'GET',
-            uri_path,
-            prepare_payload(nil),
-            headers
-          )
+        execute_request(method:) do
+          http_client.send_request(method, uri_path, prepare_payload(nil), headers)
         end
       end
 
@@ -104,29 +87,41 @@ module Lago
         }
       end
 
-      def execute_request(retry_count = 0, &block)
+      def execute_request(retry_count = 0, method: nil, &block)
         response = yield
-        handle_response(response, retry_count, block)
+        handle_response(response, retry_count, block, method:)
       end
 
-      def handle_response(response, retry_count, block)
+      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)
+          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)
+      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, &block)
+        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)

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_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

@@ -64,6 +64,7 @@ module Lago
             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

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

@@ -21,6 +21,7 @@ module Lago
             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)

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

@@ -13,6 +13,7 @@ module Lago
             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
 

data/lib/lago/version.rb

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

data/lib/lago-ruby-client.rb

@@ -12,3 +12,5 @@ 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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lago-ruby-client
 version: !ruby/object:Gem::Version
-  version: 1.46.0
+  version: 1.47.0
 platform: ruby
 authors:
 - Lovro Colic
@@ -313,7 +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