getstream-ruby 7.0.0 → 7.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 725fbf9f73fef4a9c33f241c9911d226222041e245084e2dbca69cbc0418eaef
-  data.tar.gz: 637cc6dd6bc256959b15ae6a98e62f1131f3bfdf6183e8c3f64acd6e6cfc33d2
+  metadata.gz: d60ac76c36bbf0f4fba277c49eca708e4d4784808a1c245a115dc48a05adf4f1
+  data.tar.gz: 372a04fd43e84b06c8e46eb64540124a2c4c7702066f03b415195e081137df61
 SHA512:
-  metadata.gz: 21e076ab8023229dbdda7feff3405716929d315aa96c0d0478df09c3f7b27db8a6d24e9ea399782e16cc52f355807e33adcebe558e2c040acfcb66875b8d9ed8
-  data.tar.gz: 96f2ce649e6c7f40e1651696f39c7e3612ea822e93351c3a86f0ce352b854f7a4ac12e7216f95df9933754da6a107dcb2ac6aa85892c9bc453f437c5cbf252a3
+  metadata.gz: 8ed574ba891c4692474dfc64358acc9c8c3c2b00b9d93238f333c75d5659263e0bd0006a328102344d50356e097b765bab0f69b6e9ee60ca6930710adc932c5c
+  data.tar.gz: 929b48c5fdffa86dfaf3155830493deeecba853d9bd72eae58c63fdbb235672e3920827a385b5789572ebc4fdf7c43c6641e09d8d75cba185f6a3ec0e9d8a163

data/lib/getstream_ruby/client.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 require 'faraday'
+require 'faraday/gzip'
 require 'faraday/retry'
 require 'faraday/multipart'
+require 'faraday/net_http_persistent'
+require 'logger'
 require 'json'
 require 'jwt'
 require_relative 'generated/base_model'
@@ -14,12 +17,24 @@ require_relative 'generated/video_client'
 require_relative 'extensions/moderation_extensions'
 require_relative 'generated/feed'
 require_relative 'generated/webhook'
+require_relative 'generated/models/api_error'
 require_relative 'stream_response'
+require_relative 'error_mapping'
 
 module GetStreamRuby
 
   class Client
 
+    # Backdate the JWT `iat` claim by this many seconds.
+    #
+    # JWT timestamps are whole-second (RFC 7519 NumericDate), so `Time.now.to_i`
+    # truncates to the second. The server applies minimal forward leeway on
+    # `iat`, so stamping `iat = now` lets a small fraction of requests be
+    # rejected ("token used before issue at (iat)") whenever the caller's clock
+    # is even marginally ahead of the server and the truncation lands on a
+    # second boundary. Backdating absorbs that sub-second skew.
+    AUTH_IAT_LEEWAY_SECONDS = 5
+
     attr_reader :configuration
 
     def initialize(config = nil, api_key: nil, api_secret: nil, **options)
@@ -36,6 +51,7 @@ module GetStreamRuby
 
       @configuration.validate!
       @connection = build_connection
+      @configuration.log_pool_config_to(@configuration.logger)
     end
 
     def feed_resource
@@ -130,7 +146,50 @@ module GetStreamRuby
       request(:post, path, body)
     end
 
-    def make_request(method, path, query_params: nil, body: nil)
+    # Polls the task-status endpoint until the task reaches a terminal state.
+    #
+    # Behaviour:
+    #   - status="completed": returns the task `result` payload.
+    #   - status="failed":    raises `TaskError` populated from the task's
+    #                         `ErrorResult` (`type`, `description`, `stacktrace`,
+    #                         `version`).
+    #   - timeout elapsed:    raises `TransportError` with `error_type:
+    #                         "timeout"`.
+    #
+    # @param task_id [String]
+    # @param poll_interval [Numeric] seconds between polls (default 1)
+    # @param timeout [Numeric] max seconds to wait (default 60)
+    # @return [Object] the task `result` payload on success
+    # @raise [TaskError] when the task reports `status="failed"`
+    # @raise [TransportError] when the timeout elapses (`error_type="timeout"`)
+    def wait_for_task(task_id, poll_interval: 1, timeout: 60)
+      start_time = monotonic_now
+
+      loop do
+
+        response = common.get_task(task_id)
+        status = response.status
+
+        case status
+        when 'completed'
+          return response.result
+        when 'failed'
+          raise ErrorMapping.build_task_error(task_id, response.error)
+        end
+
+        if monotonic_now - start_time >= timeout
+          raise TransportError.new(
+            "wait_for_task timed out after #{timeout}s for task_id=#{task_id}",
+            error_type: 'timeout',
+          )
+        end
+
+        sleep(poll_interval)
+
+      end
+    end
+
+    def make_request(method, path, query_params: nil, body: nil, request_timeout: nil)
       # Handle query parameters
       if query_params && !query_params.empty?
         query_string = query_params.map { |k, v| "#{k}=#{v}" }.join('&')
@@ -138,12 +197,12 @@ module GetStreamRuby
       end
 
       # Make the request
-      request(method, path, body)
+      request(method, path, body, request_timeout: request_timeout)
     end
 
     private
 
-    def request(method, path, data = {})
+    def request(method, path, data = {}, request_timeout: nil)
       # Add API key to query parameters
       query_params = { api_key: @configuration.api_key }
 
@@ -158,15 +217,20 @@ module GetStreamRuby
         req.headers['stream-auth-type'] = 'jwt'
         req.headers['X-Stream-Client'] = user_agent
         req.body = data.to_json
+        req.options.timeout = request_timeout if request_timeout
 
       end
 
       handle_response(response)
     rescue Faraday::Error => e
-      raise APIError, "Request failed: #{e.message}"
+      raise TransportError.new("Request failed: #{e.message}", error_type: ErrorMapping.classify_faraday_error(e))
     end
 
     def build_connection
+      # Escape hatch #1: user supplied a fully-built Faraday::Connection.
+      # Use it as-is; none of the 5 knobs apply.
+      return @configuration.http_client if @configuration.http_client
+
       Faraday.new(url: @configuration.base_url) do |conn|
 
         conn.request :multipart
@@ -177,28 +241,50 @@ module GetStreamRuby
           backoff_factor: 2,
         }
         conn.response :json, content_type: /\bjson$/
-        conn.headers['Connection'] = 'keep-alive' if @configuration.connection_keep_alive
+        # :gzip must come after :json (Faraday runs response middleware in reverse).
+        conn.request :gzip
         configure_adapter(conn)
-        conn.options.timeout = @configuration.timeout
+
+        conn.options.timeout = @configuration.request_timeout
+        conn.options.open_timeout = @configuration.connect_timeout
 
       end
     end
 
     def configure_adapter(connection)
-      adapter = @configuration.faraday_adapter || Faraday.default_adapter
-      adapter_options = @configuration.faraday_adapter_options || {}
-      connection.adapter(adapter, **adapter_options)
+      # Escape hatch #2: custom adapter symbol. Use it with the user's
+      # adapter_options; do NOT apply pool_size/idle_timeout (those are
+      # net_http_persistent-specific).
+      if @configuration.faraday_adapter
+        adapter = @configuration.faraday_adapter
+        adapter_options = @configuration.faraday_adapter_options || {}
+        # Header-based keep-alive only on the custom-adapter path.
+        # net_http_persistent (default) keeps connections alive natively without any HTTP header.
+        connection.headers['Connection'] = 'keep-alive' if @configuration.connection_keep_alive
+        connection.adapter(adapter, **adapter_options)
+        return
+      end
+
+      # Default: net_http_persistent with the 5-knob config.
+      # Never set Connection: close; net_http_persistent keeps connections alive natively.
+      idle = @configuration.idle_timeout
+      connection.adapter :net_http_persistent, pool_size: @configuration.max_conns_per_host do |http|
+
+        http.idle_timeout = idle
+
+      end
     rescue Faraday::Error, ArgumentError => e
-      @configuration.logger&.warn(
-        "Falling back to #{Faraday.default_adapter}: could not use adapter #{adapter} (#{e.message})",
-      )
+      # A fallback silently disables pooling, so always WARN (never swallow).
+      @configuration.warn_pool_fallback(Faraday.default_adapter, e)
       connection.adapter Faraday.default_adapter
+      # Record the adapter actually built so the INFO log reports it accurately.
+      @configuration.effective_adapter = Faraday.default_adapter.to_s
     end
 
     def generate_auth_header
       JWT.encode(
         {
-          iat: Time.now.to_i,
+          iat: Time.now.to_i - AUTH_IAT_LEEWAY_SECONDS,
           server: true,
         },
         @configuration.api_secret,
@@ -211,29 +297,13 @@ module GetStreamRuby
     end
 
     def handle_response(response)
-      case response.status
-      when 200..299
-        StreamResponse.new(response.body)
-      else
-        # Parse JSON response body if it's a string
-        parsed_body = if response.body.is_a?(String)
-                        begin
-                          JSON.parse(response.body)
-                        rescue JSON::ParserError
-                          response.body
-                        end
-                      else
-                        response.body
-                      end
-
-        error_message = if parsed_body.is_a?(Hash)
-                          parsed_body['message'] || parsed_body['detail'] ||
-                            "Request failed with status #{response.status}"
-                        else
-                          "Request failed with status #{response.status}"
-                        end
-        raise APIError, error_message
-      end
+      return StreamResponse.new(response.body) if (200..299).cover?(response.status)
+
+      ErrorMapping.raise_api_error(response)
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
     def multipart_request?(data)
@@ -249,10 +319,10 @@ module GetStreamRuby
       payload = {}
 
       # Handle file field
-      raise APIError, 'file name must be provided' if data.file.nil? || data.file.empty?
+      raise ArgumentError, 'file name must be provided' if data.file.nil? || data.file.empty?
 
       file_path = data.file
-      raise APIError, "file not found: #{file_path}" unless File.exist?(file_path)
+      raise ArgumentError, "file not found: #{file_path}" unless File.exist?(file_path)
 
       # Determine content type
       content_type = detect_content_type(file_path)
@@ -288,7 +358,7 @@ module GetStreamRuby
 
       handle_response(response)
     rescue Faraday::Error => e
-      raise APIError, "Request failed: #{e.message}"
+      raise TransportError.new("Request failed: #{e.message}", error_type: ErrorMapping.classify_faraday_error(e))
     end
 
     def detect_content_type(file_path)

data/lib/getstream_ruby/configuration.rb

@@ -1,45 +1,27 @@
 # frozen_string_literal: true
 
+require 'logger'
+
 module GetStreamRuby
 
   class Configuration
 
     attr_accessor :api_key, :api_secret, :base_url, :timeout, :logger, :faraday_adapter, :faraday_adapter_options,
-                  :connection_keep_alive
+                  :connection_keep_alive, :max_conns_per_host, :idle_timeout, :connect_timeout,
+                  :request_timeout, :http_client, :effective_adapter
 
     def initialize(api_key: nil, api_secret: nil, use_env: true, **options)
-      base_url = options[:base_url]
-      timeout = options[:timeout]
       http_options = options[:http_options] || {}
-      faraday_adapter = options[:faraday_adapter] || http_options[:faraday_adapter]
-      faraday_adapter_options = options[:faraday_adapter_options] || http_options[:faraday_adapter_options]
-      connection_keep_alive = if options.key?(:connection_keep_alive)
-                                options[:connection_keep_alive]
-                              else
-                                http_options[:connection_keep_alive]
-                              end
 
-      if use_env
-        @api_key = api_key || ENV.fetch('STREAM_API_KEY', nil)
-        @api_secret = api_secret || ENV.fetch('STREAM_API_SECRET', nil)
-        @base_url = base_url || ENV['STREAM_BASE_URL'] || 'https://chat.stream-io-api.com'
-        @timeout = timeout || (ENV['STREAM_TIMEOUT'] || 30).to_i
-      else
-        # Manual configuration only - no environment variables
-        @api_key = api_key
-        @api_secret = api_secret
-        @base_url = base_url || 'https://chat.stream-io-api.com'
-        @timeout = timeout || 30
-      end
+      assign_credentials_and_url(api_key, api_secret, options[:base_url], use_env: use_env)
+      assign_timeouts_and_pool(options, use_env: use_env)
+      assign_adapter(options, http_options)
+      assign_keep_alive(options, http_options)
 
-      @faraday_adapter = (faraday_adapter || ENV.fetch('STREAM_FARADAY_ADAPTER', nil))&.to_sym
-      @faraday_adapter_options = faraday_adapter_options || default_adapter_options
-      @connection_keep_alive = if connection_keep_alive.nil?
-                                 ENV.fetch('STREAM_CONNECTION_KEEP_ALIVE', 'true') == 'true'
-                               else
-                                 connection_keep_alive
-                               end
-      @logger = nil
+      # Keep @timeout in sync with @request_timeout for backwards compatibility.
+      @timeout = @request_timeout
+      @http_client = options[:http_client]
+      @logger = options[:logger]
     end
 
     def valid?
@@ -57,9 +39,54 @@ module GetStreamRuby
         api_secret: @api_secret,
         base_url: @base_url,
         timeout: @timeout,
+        request_timeout: @request_timeout,
+        max_conns_per_host: @max_conns_per_host,
+        idle_timeout: @idle_timeout,
+        connect_timeout: @connect_timeout,
+        http_client: @http_client,
         faraday_adapter: @faraday_adapter,
         faraday_adapter_options: @faraday_adapter_options.dup,
         connection_keep_alive: @connection_keep_alive,
+        logger: @logger,
+      )
+    end
+
+    # Emit a single INFO line listing the 5 effective pool knobs plus the active escape hatch (CHA-2956).
+    # If no logger is supplied, a default $stdout INFO logger is used.
+    # The faraday_adapter label reflects the adapter actually built
+    # (effective_adapter, set by Client#configure_adapter) so a silent fallback
+    # to the default adapter is never misreported as the requested adapter.
+    def log_pool_config_to(logger)
+      logger ||= Logger.new($stdout).tap { |l| l.level = Logger::INFO }
+      flag = @http_client ? 'user_http_client=true' : 'user_http_client=false'
+      adapter_label = if @http_client
+                        'user-supplied'
+                      elsif @effective_adapter
+                        @effective_adapter
+                      elsif @faraday_adapter
+                        @faraday_adapter.to_s
+                      else
+                        'default'
+                      end
+      fmt = 'connection pool: max_conns_per_host=%<m>d idle_timeout=%<i>d ' \
+            'connect_timeout=%<c>d request_timeout=%<r>d %<flag>s faraday_adapter=%<a>s'
+      logger.info(
+        format(
+          fmt,
+          m: @max_conns_per_host, i: @idle_timeout, c: @connect_timeout,
+          r: @request_timeout, flag: flag, a: adapter_label
+        ),
+      )
+    end
+
+    # Emit a WARNING that the requested adapter could not be built and pooling
+    # is disabled (CHA-2956). A fallback must never be silent, so when no logger
+    # is configured this uses a default $stdout logger, exactly like
+    # log_pool_config_to.
+    def warn_pool_fallback(fallback_adapter, error)
+      warn_logger = @logger || Logger.new($stdout).tap { |l| l.level = Logger::WARN }
+      warn_logger.warn(
+        "Falling back to #{fallback_adapter}: could not configure net_http_persistent (#{error.message})",
       )
     end
 
@@ -90,6 +117,59 @@ module GetStreamRuby
       {}
     end
 
+    def assign_credentials_and_url(api_key, api_secret, base_url, use_env:)
+      if use_env
+        @api_key = api_key || ENV.fetch('STREAM_API_KEY', nil)
+        @api_secret = api_secret || ENV.fetch('STREAM_API_SECRET', nil)
+        @base_url = base_url || ENV.fetch('STREAM_BASE_URL', nil) || 'https://chat.stream-io-api.com'
+      else
+        @api_key = api_key
+        @api_secret = api_secret
+        @base_url = base_url || 'https://chat.stream-io-api.com'
+      end
+    end
+
+    def assign_timeouts_and_pool(options, use_env:)
+      timeout = options[:timeout]
+      request_timeout = options[:request_timeout]
+      max_conns_per_host = options[:max_conns_per_host]
+      idle_timeout = options[:idle_timeout]
+      connect_timeout = options[:connect_timeout]
+
+      if use_env
+        env_request_timeout = ENV.fetch('STREAM_REQUEST_TIMEOUT', nil) || ENV.fetch('STREAM_TIMEOUT', nil)
+        @request_timeout = (request_timeout || timeout || env_request_timeout || 30).to_i
+        @max_conns_per_host = (max_conns_per_host || ENV.fetch('STREAM_MAX_CONNS_PER_HOST', nil) || 5).to_i
+        @idle_timeout = (idle_timeout || ENV.fetch('STREAM_IDLE_TIMEOUT', nil) || 55).to_i
+        @connect_timeout = (connect_timeout || ENV.fetch('STREAM_CONNECT_TIMEOUT', nil) || 10).to_i
+      else
+        @request_timeout = (request_timeout || timeout || 30).to_i
+        @max_conns_per_host = (max_conns_per_host || 5).to_i
+        @idle_timeout = (idle_timeout || 55).to_i
+        @connect_timeout = (connect_timeout || 10).to_i
+      end
+    end
+
+    def assign_adapter(options, http_options)
+      faraday_adapter = options[:faraday_adapter] || http_options[:faraday_adapter]
+      faraday_adapter_options = options[:faraday_adapter_options] || http_options[:faraday_adapter_options]
+      @faraday_adapter = (faraday_adapter || ENV.fetch('STREAM_FARADAY_ADAPTER', nil))&.to_sym
+      @faraday_adapter_options = faraday_adapter_options || default_adapter_options
+    end
+
+    def assign_keep_alive(options, http_options)
+      connection_keep_alive = if options.key?(:connection_keep_alive)
+                                options[:connection_keep_alive]
+                              else
+                                http_options[:connection_keep_alive]
+                              end
+      @connection_keep_alive = if connection_keep_alive.nil?
+                                 ENV.fetch('STREAM_CONNECTION_KEEP_ALIVE', 'true') == 'true'
+                               else
+                                 connection_keep_alive
+                               end
+    end
+
   end
 
 end

data/lib/getstream_ruby/error_mapping.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module GetStreamRuby
+
+  # Translates HTTP responses and Faraday errors into SDK exceptions.
+  module ErrorMapping
+
+    module_function
+
+    # Raises the appropriate `ApiError` / `RateLimitError` for a non-2xx
+    # `Faraday::Response`.
+    def raise_api_error(response)
+      parsed_body = parse_error_body(response.body)
+      raw_body = stringify_body(response.body)
+
+      if parsed_body.is_a?(Hash)
+        api_error = GetStream::Generated::Models::APIError.new(parsed_body)
+        attrs = api_error_attrs(api_error, response.status, raw_body)
+
+        if response.status == 429
+          raise RateLimitError.new(
+            retry_after: parse_retry_after(response_header(response, 'Retry-After')),
+            **attrs,
+          )
+        end
+
+        raise ApiError.new(**attrs)
+      end
+
+      raise ApiError.new(
+        message: 'failed to parse error response',
+        status_code: response.status,
+        code: 0,
+        exception_fields: {},
+        unrecoverable: false,
+        raw_response_body: raw_body,
+        more_info: nil,
+        details: nil,
+      )
+    end
+
+    def api_error_attrs(model, status, raw_body)
+      {
+        message: model.message || "Request failed with status #{status}",
+        status_code: status,
+        code: model.code || 0,
+        exception_fields: model.exception_fields || {},
+        unrecoverable: model.unrecoverable.nil? ? false : model.unrecoverable,
+        raw_response_body: raw_body,
+        more_info: model.more_info,
+        details: model.details,
+      }
+    end
+
+    def parse_error_body(body)
+      return body if body.is_a?(Hash)
+      return nil unless body.is_a?(String) && !body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def stringify_body(body)
+      return '' if body.nil?
+      return body if body.is_a?(String)
+
+      body.to_json
+    end
+
+    def response_header(response, name)
+      headers = response.headers
+      return nil if headers.nil?
+
+      # Faraday normalizes header names to lowercase, but tolerate either form.
+      headers[name] || headers[name.downcase] || headers[name.to_s]
+    end
+
+    # Parse Retry-After header. Returns Float seconds. Returns nil when absent or
+    # unparseable. Past HTTP-dates clamp to 0.
+    def parse_retry_after(header)
+      return nil if header.nil?
+
+      value = header.to_s.strip
+      return nil if value.empty?
+      return value.to_f if value.match?(/\A\d+\z/)
+
+      begin
+        target = Time.httpdate(value)
+        delta = target - Time.now
+        delta.negative? ? 0.0 : delta.to_f
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    def classify_faraday_error(error)
+      case error
+      when Faraday::TimeoutError
+        'timeout'
+      when Faraday::SSLError
+        'tls_handshake_failed'
+      when Faraday::ConnectionFailed
+        classify_connection_failure(error)
+      else
+        'unknown'
+      end
+    end
+
+    def classify_connection_failure(error)
+      wrapped = error.respond_to?(:wrapped_exception) ? error.wrapped_exception : nil
+      case wrapped
+      when SocketError
+        'dns_failure'
+      else
+        'connection_reset'
+      end
+    end
+
+    def build_task_error(task_id, error_payload)
+      hash = if error_payload.respond_to?(:to_h)
+               error_payload.to_h
+             else
+               error_payload || {}
+             end
+      TaskError.new(
+        task_id: task_id,
+        error_type: lookup(hash, :type) || '',
+        description: lookup(hash, :description) || '',
+        stack_trace: lookup(hash, :stacktrace),
+        version: lookup(hash, :version),
+      )
+    end
+
+    def lookup(hash, key)
+      hash[key] || hash[key.to_s]
+    end
+
+  end
+
+end

data/lib/getstream_ruby/errors.rb

@@ -2,8 +2,112 @@
 
 module GetStreamRuby
 
-  class Error < StandardError; end
-  class ConfigurationError < Error; end
-  class APIError < Error; end
+  # Base error class for the SDK. Every SDK-raised exception is a subclass.
+  class StreamError < StandardError; end
+
+  # Back-compat alias. The prior base class was `Error`; keep it usable so
+  # any existing `rescue GetStreamRuby::Error` clauses keep matching.
+  Error = StreamError
+
+  class ConfigurationError < StreamError; end
+
+  # Raised on any HTTP 4xx/5xx response. Also raised when an HTTP response is
+  # received but its body is not a parseable `APIError` envelope, with `code = 0`
+  # and `message = "failed to parse error response"`.
+  class ApiError < StreamError
+
+    attr_reader :status_code, :code, :exception_fields, :unrecoverable,
+                :raw_response_body, :more_info, :details
+
+    def initialize(message:, status_code:, code:, exception_fields: nil,
+                   unrecoverable: nil, raw_response_body: nil,
+                   more_info: nil, details: nil)
+      super(message)
+      @status_code = status_code
+      @code = code
+      @exception_fields = exception_fields || {}
+      @unrecoverable = unrecoverable.nil? ? false : unrecoverable
+      @raw_response_body = raw_response_body || ''
+      @more_info = more_info
+      @details = details
+    end
+
+  end
+
+  # Raised on HTTP 429. Adds parsed `Retry-After` as Float seconds, or nil when
+  # the header is absent or unparseable. Per RFC 7231, both integer-seconds and
+  # HTTP-date forms are supported. Past HTTP-dates clamp to 0.
+  class RateLimitError < ApiError
+
+    attr_reader :retry_after
+
+    def initialize(retry_after: nil, **kwargs)
+      super(**kwargs)
+      @retry_after = retry_after
+    end
+
+  end
+
+  # Allowed values for `TransportError#error_type`.
+  TRANSPORT_ERROR_TYPES = %w[
+    connection_reset
+    timeout
+    dns_failure
+    tls_handshake_failed
+    unknown
+  ].freeze
+
+  # Raised when no HTTP response is received: connection reset, timeout, TLS
+  # handshake failure, DNS failure. Always raised inside the matching `rescue`
+  # block so Ruby auto-sets `Exception#cause` to the underlying Faraday error.
+  class TransportError < StreamError
+
+    attr_reader :error_type
+
+    def initialize(message = nil, error_type: 'unknown')
+      super(message)
+      @error_type = error_type
+    end
+
+  end
+
+  # Raised by `Client#wait_for_task` when an async task finishes with
+  # status="failed". Carries the populated `ErrorResult` fields.
+  class TaskError < StreamError
+
+    attr_reader :task_id, :error_type, :description, :stack_trace, :version
+
+    def initialize(task_id:, error_type:, description:,
+                   stack_trace: nil, version: nil)
+      super(description)
+      @task_id = task_id
+      @error_type = error_type
+      @description = description
+      @stack_trace = stack_trace
+      @version = version
+    end
+
+  end
+
+  # Deprecated alias for ApiError. Will be removed in v9.0.
+  # Implemented via `const_missing` so the first access emits a `Kernel.warn`
+  # once-only and the constant is cached afterwards (no per-rescue noise).
+  @apierror_alias_warned = false
+
+  def self.const_missing(name)
+    if name == :APIError
+      unless @apierror_alias_warned
+        Kernel.warn(
+          '[DEPRECATION] GetStreamRuby::APIError is renamed to ' \
+          'GetStreamRuby::ApiError. The old constant will be removed in v9.0.',
+        )
+        @apierror_alias_warned = true
+      end
+      const_set(:APIError, ApiError)
+      ApiError
+    else
+      super
+    end
+  end
 
 end

data/lib/getstream_ruby/generated/webhook.rb

@@ -817,7 +817,7 @@ module StreamChat
     # detection decides whether to decompress.
     #
     # {parse_sqs} sits on top of this and works transparently for both wire
-    # formats — no caller code change, no flag, no header.
+    # formats: no caller code change, no flag, no header.
     #
     # @param message_body [String]
     # @return [String]
@@ -829,7 +829,7 @@ module StreamChat
         begin
           Base64.strict_decode64(message_body)
         rescue ArgumentError
-          # Not base64 — treat input as raw bytes (uncompressed wire format).
+          # Not base64, so treat input as raw bytes (uncompressed wire format).
           message_body.dup.force_encoding(Encoding::ASCII_8BIT)
         end
       gunzip_payload(decoded)
@@ -840,7 +840,7 @@ module StreamChat
     # pre-extracted Message string flows through.
     #
     # Heuristic: try to JSON-parse the input. If it yields a Hash with a
-    # String +Message+ field, that's the envelope shape — return the Message.
+    # String +Message+ field, that's the envelope shape; return the Message.
     # Otherwise the input is presumed to BE the pre-extracted Message
     # (base64-encoded bytes are not valid JSON, so this falls through cleanly).
     def self.unwrap_sns_notification_body(body)

data/lib/getstream_ruby/version.rb

@@ -2,6 +2,6 @@
 
 module GetStreamRuby
 
-  VERSION = '7.0.0'
+  VERSION = '7.1.1'
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: getstream-ruby
 version: !ruby/object:Gem::Version
-  version: 7.0.0
+  version: 7.1.1
 platform: ruby
 authors:
 - GetStream
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-22 00:00:00.000000000 Z
+date: 2026-06-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dotenv
@@ -30,14 +30,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: faraday-gzip
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: faraday-multipart
   requirement: !ruby/object:Gem::Requirement
@@ -52,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-net_http_persistent
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: faraday-retry
   requirement: !ruby/object:Gem::Requirement
@@ -94,6 +122,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: net-http-persistent
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
 description: Official Ruby SDK for GetStream's activity feeds and chat APIs
 email:
 - support@getstream.io
@@ -105,6 +147,7 @@ files:
 - lib/getstream_ruby.rb
 - lib/getstream_ruby/client.rb
 - lib/getstream_ruby/configuration.rb
+- lib/getstream_ruby/error_mapping.rb
 - lib/getstream_ruby/errors.rb
 - lib/getstream_ruby/extensions/moderation_extensions.rb
 - lib/getstream_ruby/generated/base_model.rb