inttegro 4.2.2 → 4.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 898d14cfaa38b878c20565b4522fe67d87147f01850656bf5a7817da99c955a2
-  data.tar.gz: 32a2dc36592ebdfa52c4076687d7b5c4512ac887de57285fccb843815a0e64e7
+  metadata.gz: 523d5315b309ba6414799b21dfb52eef979e45e4770a0056dff87e787d96159f
+  data.tar.gz: 92b8163c7f228c73dea65a03ec6680f70722744ad731137ddac6c2215c5e2dd1
 SHA512:
-  metadata.gz: 5c3dff6b6e94712d541d1c4aabe3ee49227cd35ce1d4decc7656eff992be17ad0fec34177b5e7e3fd84514e0e79558f7ee552bb889f025cacb77b69381d9fbc2
-  data.tar.gz: f55e5ed4ea3703b3ef98042add688bb97224dfcebe5c102455544a9984745bf7d855aa8bd3ae30f9971c3de2af1ecac68f11f5ebadafec2a4212c2b933c68ba1
+  metadata.gz: aef00a637c73a440acbd0d5a3150e93f63ea38b251a09a19830ddf6e372179a487d4ed817f3cb07f93f526abd4e7907ec7493b8994c8db74ce7a940115f07869
+  data.tar.gz: 71954cf59f4cc95a178b6f363bcb92e9c7cabb7123add536485089011c71b98e1b0f18cfe0efa5f865c0e4dd9cd8534334b17c6b99088a6436ad4a9cd6bdadd5

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [4.3.0] - 2026-09-06
+
+- Added opt-in, typed error reporting to application-owned collectors with privacy-safe payloads, stable fingerprints, isolated reporter failures, and no reporting work when unconfigured.
+
 ## [4.2.2] - 2026-09-04
 
 - Constrained OpenTelemetry dependencies to releases that preserve the SDK's Ruby 3.0 runtime support, while declaring `logger` for Ruby 4 compatibility.

data/README.md

@@ -87,6 +87,21 @@ inttegro = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
 
 Spans are named after logical operations such as `inttegro.orders.create`. HTTP attempts, response receipt, and decoding are span events. API keys, bodies, resource IDs, dynamic URLs, and exception messages are never recorded. See [SDK observability](https://studio.inttegro.com/sdk-observability) for the complete contract and set `telemetry_enabled: false` when needed.
 
+### Report SDK failures
+
+Provide an application-owned reporter to receive one immutable, typed, privacy-safe report after an SDK operation finally fails. The default `:unexpected` policy reports transport, timeout, decoding, SDK, `unknown_error`, and server-side failures while leaving normal 4xx API errors alone:
+
+```ruby
+inttegro = Inttegro::Client.new(
+  api_key: ENV.fetch("INTTEGRO_API_KEY"),
+  error_reporter: ->(report) { ErrorCollector.enqueue(report.serialize) }
+)
+```
+
+Use `error_reporting_policy: :all` to include expected API failures; cancellations are never reported. Reports contain the logical operation, static route, server host, status and request IDs when available, duration, safe API error codes, SDK identity, stable fingerprint, exception type, and trace IDs when tracing is active. They exclude credentials, headers, bodies, resource IDs, dynamic URLs, exception messages, and stack traces. Reporter failures are isolated and the original SDK error is still raised.
+
+Error reporting is completely opt-in. Without `error_reporter`, the SDK does not calculate report metadata, create an event ID or timestamp, allocate a report, or serialize a payload.
+
 ## Work with the API
 
 The SDK covers orders and checkout, customers, products and prices, purchase intents, payment methods, balances, payouts and refunds, notifications, files, application settings, keys, and country specifications. Resources use snake-case readers such as `purchase_intents` and `payment_methods`.

data/lib/inttegro/client.rb

@@ -111,7 +111,9 @@ module Inttegro
         open_timeout: T.nilable(Numeric),
         adapter: T.nilable(Types::Adapter),
         telemetry_enabled: T::Boolean,
-        tracer_provider: T.nilable(OpenTelemetry::Trace::TracerProvider)
+        tracer_provider: T.nilable(OpenTelemetry::Trace::TracerProvider),
+        error_reporter: T.nilable(ErrorReporter),
+        error_reporting_policy: Symbol
       ).void
     end
     def initialize(
@@ -123,7 +125,9 @@ module Inttegro
       open_timeout: 10,
       adapter: nil,
       telemetry_enabled: true,
-      tracer_provider: nil
+      tracer_provider: nil,
+      error_reporter: nil,
+      error_reporting_policy: :unexpected
     )
       provided_token = token || token_value
       api_key ||= provided_token
@@ -134,7 +138,9 @@ module Inttegro
         open_timeout: open_timeout,
         adapter: adapter,
         telemetry_enabled: telemetry_enabled,
-        tracer_provider: tracer_provider
+        tracer_provider: tracer_provider,
+        error_reporter: error_reporter,
+        error_reporting_policy: error_reporting_policy
       ), HTTPClient)
 
       @orders = T.let(Resources::Orders.new(@http), Resources::Orders)

data/lib/inttegro/error_reporting.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+# typed: strict
+
+require "sorbet-runtime"
+
+module Inttegro
+  # SDK identity included in an ErrorReport.
+  class SDKReportContext < T::Struct
+    const :language, String
+    const :version, String
+  end
+
+  # Bounded HTTP metadata included in an ErrorReport.
+  class HTTPReportContext < T::Struct
+    const :request_method, String
+    const :server_address, String
+    const :duration_ms, Integer
+    const :route, T.nilable(String), default: nil
+    const :status_code, T.nilable(Integer), default: nil
+    const :request_id, T.nilable(String), default: nil
+  end
+
+  # Machine-readable API error metadata included in an ErrorReport.
+  class APIErrorReportContext < T::Struct
+    const :type, T.nilable(String), default: nil
+    const :code, T.nilable(String), default: nil
+    const :fix_code, T.nilable(String), default: nil
+  end
+
+  # Trace identifiers included when application tracing is enabled.
+  class TraceReportContext < T::Struct
+    const :trace_id, String
+    const :span_id, String
+  end
+
+  # Privacy-safe description of a failed Inttegro SDK operation.
+  class ErrorReport < T::Struct
+    const :schema_version, Integer
+    const :event_id, String
+    const :occurred_at, String
+    const :severity, String
+    const :category, String
+    const :operation, String
+    const :sdk, SDKReportContext
+    const :http, HTTPReportContext
+    const :exception_type, String
+    const :fingerprint, String
+    const :api_error, T.nilable(APIErrorReportContext), default: nil
+    const :trace, T.nilable(TraceReportContext), default: nil
+  end
+
+  ErrorReporter = T.type_alias { T.proc.params(report: ErrorReport).void }
+end

data/lib/inttegro/errors.rb

@@ -4,9 +4,21 @@
 require "sorbet-runtime"
 
 require_relative "types"
+require_relative "error_reporting"
 
 module Inttegro
-  class Error < StandardError; end
+  class Error < StandardError
+    extend T::Sig
+
+    sig { returns(T.nilable(ErrorReport)) }
+    attr_accessor :report
+
+    sig { params(message: String).void }
+    def initialize(message)
+      super(message)
+      @report = T.let(nil, T.nilable(ErrorReport))
+    end
+  end
 
   class NetworkError < Error
     extend T::Sig
@@ -30,7 +42,7 @@ module Inttegro
     attr_reader :status
 
     sig { returns(T.nilable(String)) }
-    attr_reader :code, :type, :url, :detail, :fix_code, :cause, :body
+    attr_reader :code, :type, :url, :detail, :fix_code, :cause, :body, :request_id
 
     sig { returns(Types::WireValue) }
     attr_reader :data
@@ -46,7 +58,8 @@ module Inttegro
         fix_code: T.nilable(String),
         cause: T.nilable(String),
         body: T.nilable(String),
-        data: Types::WireValue
+        data: Types::WireValue,
+        request_id: T.nilable(String)
       ).void
     end
     def initialize(
@@ -59,7 +72,8 @@ module Inttegro
       fix_code: nil,
       cause: nil,
       body: nil,
-      data: nil
+      data: nil,
+      request_id: nil
     )
       super(message)
       @status = status
@@ -71,6 +85,7 @@ module Inttegro
       @cause = cause
       @body = body
       @data = data
+      @request_id = request_id
     end
   end
 
@@ -94,7 +109,8 @@ module Inttegro
         cause: T.nilable(String),
         body: T.nilable(String),
         data: Types::WireValue,
-        retry_after: T.nilable(Integer)
+        retry_after: T.nilable(Integer),
+        request_id: T.nilable(String)
       ).void
     end
     def initialize(
@@ -108,7 +124,8 @@ module Inttegro
       cause: nil,
       body: nil,
       data: nil,
-      retry_after: nil
+      retry_after: nil,
+      request_id: nil
     )
       super(
         message,
@@ -120,7 +137,8 @@ module Inttegro
         fix_code: fix_code,
         cause: cause,
         body: body,
-        data: data
+        data: data,
+        request_id: request_id
       )
       @retry_after = retry_after
     end

data/lib/inttegro/http_client.rb

@@ -37,7 +37,9 @@ module Inttegro
         open_timeout: T.nilable(Numeric),
         adapter: T.nilable(Types::Adapter),
         telemetry_enabled: T::Boolean,
-        tracer_provider: T.nilable(OpenTelemetry::Trace::TracerProvider)
+        tracer_provider: T.nilable(OpenTelemetry::Trace::TracerProvider),
+        error_reporter: T.nilable(ErrorReporter),
+        error_reporting_policy: Symbol
       ).void
     end
     def initialize(
@@ -47,7 +49,9 @@ module Inttegro
       open_timeout: 10,
       adapter: nil,
       telemetry_enabled: true,
-      tracer_provider: nil
+      tracer_provider: nil,
+      error_reporter: nil,
+      error_reporting_policy: :unexpected
     )
       @api_key = T.let(api_key || "", String)
       raise ArgumentError, "api_key is required" if @api_key.strip.empty?
@@ -60,7 +64,13 @@ module Inttegro
       @open_timeout = T.let(open_timeout, T.nilable(Numeric))
       @adapter = T.let(adapter, T.nilable(Types::Adapter))
       @telemetry = T.let(
-        Telemetry.new(Inttegro::VERSION, enabled: telemetry_enabled, tracer_provider: tracer_provider),
+        Telemetry.new(
+          Inttegro::VERSION,
+          enabled: telemetry_enabled,
+          tracer_provider: tracer_provider,
+          error_reporter: error_reporter,
+          error_reporting_policy: error_reporting_policy
+        ),
         Telemetry
       )
     end
@@ -504,6 +514,7 @@ module Inttegro
       detail = payload[:detail]
       fix_code = payload[:fix_code]
       cause = payload[:cause]
+      request_id = response["x-request-id"] || response["X-Request-Id"]
 
       case status
       when 401
@@ -517,7 +528,8 @@ module Inttegro
           fix_code: fix_code,
           cause: cause,
           body: body,
-          data: data
+          data: data,
+          request_id: request_id
         )
       when 429
         retry_after = response["Retry-After"]&.to_i
@@ -532,7 +544,8 @@ module Inttegro
           cause: cause,
           body: body,
           data: data,
-          retry_after: retry_after
+          retry_after: retry_after,
+          request_id: request_id
         )
       else
         raise APIError.new(
@@ -545,7 +558,8 @@ module Inttegro
           fix_code: fix_code,
           cause: cause,
           body: body,
-          data: data
+          data: data,
+          request_id: request_id
         )
       end
     end

data/lib/inttegro/telemetry.rb

@@ -3,9 +3,12 @@
 
 require "opentelemetry-api"
 require "sorbet-runtime"
+require "securerandom"
+require "time"
 require "uri"
 
 require_relative "errors"
+require_relative "error_reporting"
 
 module Inttegro
   # Emits redacted SDK spans to the application's OpenTelemetry provider.
@@ -30,11 +33,17 @@ module Inttegro
       params(
         version: String,
         enabled: T::Boolean,
-        tracer_provider: T.nilable(OpenTelemetry::Trace::TracerProvider)
+        tracer_provider: T.nilable(OpenTelemetry::Trace::TracerProvider),
+        error_reporter: T.nilable(ErrorReporter),
+        error_reporting_policy: Symbol
       ).void
     end
-    def initialize(version, enabled: true, tracer_provider: nil)
+    def initialize(version, enabled: true, tracer_provider: nil, error_reporter: nil, error_reporting_policy: :unexpected)
       @enabled = T.let(enabled, T::Boolean)
+      raise ArgumentError, "error_reporting_policy must be :unexpected or :all" unless %i[unexpected all].include?(error_reporting_policy)
+
+      @error_reporter = T.let(error_reporter, T.nilable(ErrorReporter))
+      @error_reporting_policy = T.let(error_reporting_policy, Symbol)
       provider = tracer_provider || OpenTelemetry.tracer_provider
       @tracer = T.let(provider.tracer("inttegro", version), OpenTelemetry::Trace::Tracer)
     end
@@ -52,9 +61,18 @@ module Inttegro
         .returns(T.type_parameter(:Result))
     end
     def in_span(path_or_url, method, base_url, version, operation_override = nil, &block)
-      return yield(nil) unless @enabled
+      return yield(nil) unless @enabled || @error_reporter
 
       operation, route, server_address = request_details(path_or_url, base_url, operation_override)
+      started_at = T.let(@error_reporter ? monotonic_milliseconds : nil, T.nilable(Float))
+      unless @enabled
+        begin
+          return yield(nil)
+        rescue StandardError => e
+          report_failure(e, operation, route, server_address, method, version, started_at, nil)
+          raise
+        end
+      end
       attributes = {
         "inttegro.operation.name" => operation,
         "inttegro.sdk.language" => "ruby",
@@ -72,6 +90,7 @@ module Inttegro
         span.set_attribute("error.type", error_type)
         span.status = OpenTelemetry::Trace::Status.error
         span.add_event("inttegro.request.failed", attributes: { "error.type" => error_type })
+        report_failure(e, operation, route, server_address, method, version, started_at, span)
         raise
       ensure
         span.finish
@@ -125,6 +144,71 @@ module Inttegro
 
     private
 
+    sig do
+      params(
+        error: StandardError,
+        operation: String,
+        route: T.nilable(String),
+        server_address: String,
+        method: T.any(String, Symbol),
+        version: String,
+        started_at: T.nilable(Float),
+        span: T.nilable(OpenTelemetry::Trace::Span)
+      ).void
+    end
+    def report_failure(error, operation, route, server_address, method, version, started_at, span)
+      reporter = @error_reporter
+      return unless reporter
+
+      begin
+        category = classify_error(error)
+        return if category == "canceled"
+        if @error_reporting_policy == :unexpected && error.is_a?(APIError)
+          return unless error.status >= 500 || error.type == "unknown_error"
+        end
+
+        api_error = T.let(error.is_a?(APIError) ? error : nil, T.nilable(APIError))
+        api_context = if api_error && (api_error.type || api_error.code || api_error.fix_code)
+          APIErrorReportContext.new(type: api_error.type, code: api_error.code, fix_code: api_error.fix_code)
+        end
+        span_context = span&.context
+        trace_context = if span_context&.valid?
+          TraceReportContext.new(trace_id: span_context.hex_trace_id, span_id: span_context.hex_span_id)
+        end
+        status_code = api_error&.status
+        report = ErrorReport.new(
+          schema_version: 1,
+          event_id: SecureRandom.uuid,
+          occurred_at: Time.now.utc.iso8601(6),
+          severity: "error",
+          category: category,
+          operation: operation,
+          sdk: SDKReportContext.new(language: "ruby", version: version),
+          http: HTTPReportContext.new(
+            request_method: method.to_s.upcase,
+            route: route,
+            server_address: server_address,
+            status_code: status_code,
+            request_id: api_error&.request_id,
+            duration_ms: [(monotonic_milliseconds - (started_at || monotonic_milliseconds)).round, 0].max
+          ),
+          api_error: api_context,
+          trace: trace_context,
+          exception_type: (error.class.name || "StandardError").split("::").last || "StandardError",
+          fingerprint: ["inttegro", "ruby", operation, category, status_code || "none"].join(":")
+        )
+        error.report = report if error.is_a?(Error)
+        reporter.call(report)
+      rescue StandardError
+        # Report preparation and delivery must never replace the original failure.
+      end
+    end
+
+    sig { returns(Float) }
+    def monotonic_milliseconds
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond).to_f
+    end
+
     sig do
       params(path_or_url: String, base_url: String, override: T.nilable(String))
         .returns([String, T.nilable(String), String])

data/lib/inttegro/version.rb

@@ -2,5 +2,5 @@
 # typed: strict
 
 module Inttegro
-  VERSION = "4.2.2"
+  VERSION = "4.3.0"
 end

data/lib/inttegro.rb

@@ -6,6 +6,7 @@ require "sorbet-runtime"
 require_relative "inttegro/types"
 require_relative "inttegro/client"
 require_relative "inttegro/errors"
+require_relative "inttegro/error_reporting"
 require_relative "inttegro/enums"
 require_relative "inttegro/models"
 require_relative "inttegro/version"

data/rbi/opentelemetry-api.rbi

@@ -56,6 +56,9 @@ module OpenTelemetry
     end
 
     class Span
+      sig { returns(SpanContext) }
+      def context; end
+
       sig { params(key: String, value: Object).returns(Span) }
       def set_attribute(key, value); end
 
@@ -69,6 +72,17 @@ module OpenTelemetry
       def finish; end
     end
 
+    class SpanContext
+      sig { returns(T::Boolean) }
+      def valid?; end
+
+      sig { returns(String) }
+      def hex_trace_id; end
+
+      sig { returns(String) }
+      def hex_span_id; end
+    end
+
     class Status
       sig { params(description: String).returns(Status) }
       def self.error(description = ""); end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: inttegro
 version: !ruby/object:Gem::Version
-  version: 4.2.2
+  version: 4.3.0
 platform: ruby
 authors:
 - Inttegro Engineering
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-04 00:00:00.000000000 Z
+date: 2026-09-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime
@@ -82,6 +82,7 @@ files:
 - lib/inttegro.rb
 - lib/inttegro/client.rb
 - lib/inttegro/enums.rb
+- lib/inttegro/error_reporting.rb
 - lib/inttegro/errors.rb
 - lib/inttegro/file_download.rb
 - lib/inttegro/generated/enums.rb