inttegro 4.1.0 → 4.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70427e59f95d2e1432182e67f4192df8a3c76b8246afcfa6f5247898f99d6681
-  data.tar.gz: dd9374452a04136400903a24a80bbd3b6b983571c213540080d2a04b262c4e91
+  metadata.gz: 7b60affd2f9bc5ce1556ec7aeeacc26d0d52604d964df3c0ffd72ae034800130
+  data.tar.gz: 93520c2c26b96c4292eace71528343cd5ff5f33039e563132c3161d07dce03fe
 SHA512:
-  metadata.gz: 64ff092d9abf19ead2714be30d1a05be574b59a5d059d1dea76b2d94303714593ae0b5b0be4f6f1f4c0d640c0aafc87bfac74bbe69bca43ac1247635e725b21b
-  data.tar.gz: 14df7fb8165c4201be2268c77774f01c3b7d7652ec50c080f506a861655762fbe819a25316292667fc9f1bc2fcaa830f7ebf591c54d97a8d03314c05cd5da5e1
+  metadata.gz: 42d25f00a4b8d6ce066f044b2572fd31f3a49aaac7fb98085817673816695b2b69cb83e93e1381c685a5da73236cc9c663e8e493ab3e3118e28698b7e22e1cf9
+  data.tar.gz: 22b17729fa018888d51fc33945536a6624298f1b8b66a6a2599b3009fce8a79575e574dc4caefc531535e5812c64b397ce87ebd5f3eff908307890a12934f830

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [4.2.1] - 2026-09-04
+
+- Aligned the SDK parity test with hosted-checkout routes that are intentionally handled by the client.
+- Refreshed generated declarations from the OpenAPI commit pinned by CI and release automation.
+
+## [4.2.0] - 2026-09-04
+
+- Added vendor-neutral OpenTelemetry spans for logical SDK operations, HTTP attempts, response receipt, decoding, and safe failure categories.
+- Added W3C trace-context propagation plus global or per-client tracer-provider configuration.
+- Kept request bodies, credentials, resource identifiers, dynamic URLs, and exception details out of telemetry.
+
 ## [4.1.0] - 2026-09-03
 
 - Added focused `Inttegro::Wallets` and `Inttegro::BankAccounts` modules for financial-account variants.

data/README.md

@@ -73,6 +73,20 @@ end
 
 Amounts use integer minor units: `5000` GHS is GHS 50.00. Reuse the same idempotency key when retrying the same logical write. If you omit one, the SDK generates a UUIDv7 key for mutating calls.
 
+## Observe SDK operations
+
+The SDK emits vendor-neutral OpenTelemetry spans through your application's provider. It never configures an exporter or sends telemetry by itself. Configure OpenTelemetry before creating the client:
+
+```ruby
+require "opentelemetry/sdk"
+require "inttegro"
+
+OpenTelemetry::SDK.configure
+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.
+
 ## 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`.
@@ -95,7 +109,7 @@ The GitHub release for each version is the canonical record. It contains the exa
 
 ```bash
 sha256sum --check SHA256SUMS
-gh attestation verify inttegro-4.1.0.gem \
+gh attestation verify inttegro-4.2.1.gem \
   --repo zebodotdev/inttegro-sdk-ruby
 ```
 

data/lib/inttegro/client.rb

@@ -109,7 +109,9 @@ module Inttegro
         base_url: T.nilable(String),
         read_timeout: T.nilable(Numeric),
         open_timeout: T.nilable(Numeric),
-        adapter: T.nilable(Types::Adapter)
+        adapter: T.nilable(Types::Adapter),
+        telemetry_enabled: T::Boolean,
+        tracer_provider: T.nilable(OpenTelemetry::Trace::TracerProvider)
       ).void
     end
     def initialize(
@@ -119,7 +121,9 @@ module Inttegro
       base_url: DEFAULT_BASE_URL,
       read_timeout: 30,
       open_timeout: 10,
-      adapter: nil
+      adapter: nil,
+      telemetry_enabled: true,
+      tracer_provider: nil
     )
       provided_token = token || token_value
       api_key ||= provided_token
@@ -128,7 +132,9 @@ module Inttegro
         base_url: base_url,
         read_timeout: read_timeout,
         open_timeout: open_timeout,
-        adapter: adapter
+        adapter: adapter,
+        telemetry_enabled: telemetry_enabled,
+        tracer_provider: tracer_provider
       ), HTTPClient)
 
       @orders = T.let(Resources::Orders.new(@http), Resources::Orders)

data/lib/inttegro/generated/enums.rb

@@ -47,6 +47,50 @@ module Inttegro
     end
   end
 
+  class CheckoutInvoiceViewStatus < T::Enum
+    enums do
+      DRAFT = new("draft")
+      REQUIRES_PAYMENT = new("requires_payment")
+      OVERDUE = new("overdue")
+      PAID = new("paid")
+      EXPIRED = new("expired")
+      CANCELED = new("canceled")
+    end
+  end
+
+  class CheckoutMobileMoneyDataNetwork < T::Enum
+    enums do
+      MTN = new("mtn")
+      VODAFONE = new("vodafone")
+      AIRTEL = new("airtel")
+      TELECEL = new("telecel")
+    end
+  end
+
+  class CheckoutOrderStatus < T::Enum
+    enums do
+      PREPARING = new("preparing")
+      REQUIRES_PAYMENT = new("requires_payment")
+      COMPLETED = new("completed")
+      PAID = new("paid")
+      CANCELED = new("canceled")
+      EXPIRED = new("expired")
+      UNKNOWN = new("unknown")
+    end
+  end
+
+  class CheckoutPayRequestPaymentMethodDataType < T::Enum
+    enums do
+      MOBILE_MONEY = new("mobile_money")
+    end
+  end
+
+  class CheckoutPaymentMethodDataType < T::Enum
+    enums do
+      MOBILE_MONEY = new("mobile_money")
+    end
+  end
+
   class ChimeEmailSchemaKind < T::Enum
     enums do
       GMAIL_VIEW_ACTION = new("gmail_view_action")

data/lib/inttegro/generated/models.rb

@@ -562,6 +562,256 @@ module Inttegro
     const :quantity, Integer
   end
 
+  class CheckoutPaymentAddress < T::Struct
+    const :name, T.nilable(String), default: nil
+    const :phone_number, T.nilable(String), default: nil
+    const :line1, T.nilable(String), default: nil
+    const :line2, T.nilable(String), default: nil
+    const :city, T.nilable(String), default: nil
+    const :region, T.nilable(String), default: nil
+    const :post_code, T.nilable(String), default: nil
+    const :country, String
+  end
+
+  class CheckoutBillingDetails < T::Struct
+    const :name, String
+    const :phone_number, T.nilable(String), default: nil
+    const :address, Inttegro::CheckoutPaymentAddress
+  end
+
+  class CheckoutConfirmPaymentRequest < T::Struct
+    const :order_id, String
+    const :payment_id, T.nilable(String), default: nil
+    const :confirmation_id, T.nilable(String), default: nil
+    const :token, String
+  end
+
+  class CheckoutInvoiceViewFormatWeb < T::Struct
+    const :url, T.nilable(String), default: nil
+  end
+
+  class CheckoutInvoiceViewFormatPdf < T::Struct
+    const :url, T.nilable(String), default: nil
+  end
+
+  class CheckoutInvoiceViewFormatReceipt < T::Struct
+    const :url, T.nilable(String), default: nil
+  end
+
+  class CheckoutInvoiceViewFormat < T::Struct
+    const :web, T.nilable(Inttegro::CheckoutInvoiceViewFormatWeb), default: nil
+    const :pdf, T.nilable(Inttegro::CheckoutInvoiceViewFormatPdf), default: nil
+    const :receipt, T.nilable(Inttegro::CheckoutInvoiceViewFormatReceipt), default: nil
+  end
+
+  class CheckoutInvoiceViewBeneficiary < T::Struct
+    const :id, T.nilable(String), default: nil
+    const :legal_entity_type, T.nilable(String), default: nil
+    const :logo_url, T.nilable(String), default: nil
+    const :alias, T.nilable(String), default: nil
+    const :name, T.nilable(String), default: nil
+    const :support_email, T.nilable(String), default: nil
+    const :support_phone, T.nilable(String), default: nil
+    const :website_url, T.nilable(String), default: nil
+    const :accent_color, T.nilable(String), default: nil
+    const :invoice_support_line, T.nilable(String), default: nil
+    const :invoice_footer, T.nilable(String), default: nil
+  end
+
+  class CheckoutInvoiceView < T::Struct
+    const :id, String
+    const :application_id, T.nilable(String), default: nil
+    const :number, T.nilable(String), default: nil
+    const :status, T.nilable(Inttegro::CheckoutInvoiceViewStatus), default: nil
+    const :created_at, String
+    const :due_at, T.nilable(String), default: nil
+    const :format_value, Inttegro::CheckoutInvoiceViewFormat, name: "format"
+    const :beneficiary, T.nilable(Inttegro::CheckoutInvoiceViewBeneficiary), default: nil
+  end
+
+  class CheckoutMobileMoneyData < T::Struct
+    const :reference, T.nilable(String), default: nil
+    const :network, Inttegro::CheckoutMobileMoneyDataNetwork
+    const :account_number, String
+  end
+
+  class CheckoutOrderCheckoutSettings < T::Struct
+    const :redirect_url, T.nilable(String), default: nil
+    const :cancel_url, T.nilable(String), default: nil
+  end
+
+  class InlineProductDetails < T::Struct
+    const :about, T.nilable(String), default: nil
+    const :custom_data, T.nilable(T::Hash[String, Object]), default: nil
+    const :name, String
+    const :price, Inttegro::PriceParams
+    const :quantity, Integer
+    const :reference, T.nilable(String), default: nil
+    const :tax_code, T.nilable(String), default: nil
+    const :type, Inttegro::ProductType
+  end
+
+  ProductDetails = T.type_alias { T.any(Inttegro::InlineProductDetails, Inttegro::CatalogProductWithPriceData, Inttegro::CatalogProductWithPriceReference) }
+
+  class ProductLineItem < T::Struct
+    const :type, Inttegro::ProductLineItemType
+    const :product, Inttegro::ProductDetails
+  end
+
+  class FeeDetails < T::Struct
+    const :id, T.nilable(String), default: nil
+    const :label, T.nilable(String), default: nil
+    const :tax_code, T.nilable(String), default: nil
+    const :description, T.nilable(String), default: nil
+    const :custom_data, T.nilable(T::Hash[String, Object]), default: nil
+    const :amount, Inttegro::AmountParams
+  end
+
+  class FeeLineItem < T::Struct
+    const :type, Inttegro::FeeLineItemType
+    const :fee, Inttegro::FeeDetails
+  end
+
+  class ShippingDetails < T::Struct
+    const :id, T.nilable(String), default: nil
+    const :tax_code, T.nilable(String), default: nil
+    const :custom_data, T.nilable(T::Hash[String, Object]), default: nil
+    const :fee, Inttegro::AmountParams
+  end
+
+  class ShippingLineItem < T::Struct
+    const :type, Inttegro::ShippingLineItemType
+    const :shipping, Inttegro::ShippingDetails
+  end
+
+  LineItem = T.type_alias { T.any(Inttegro::ProductLineItem, Inttegro::FeeLineItem, Inttegro::ShippingLineItem) }
+
+  class CheckoutOrderLineItemGroup < T::Struct
+    const :line_items, T.nilable(T::Array[Inttegro::LineItem]), default: nil
+    const :total, T.nilable(Inttegro::Amount), default: nil
+  end
+
+  class CheckoutOrderCustomerBillingAddress < T::Struct
+    # This object intentionally has no fields.
+  end
+
+  class CheckoutOrderCustomerShippingAddress < T::Struct
+    # This object intentionally has no fields.
+  end
+
+  class CheckoutOrderCustomer < T::Struct
+    const :id, T.nilable(String), default: nil
+    const :guest, T.nilable(T::Boolean), default: nil
+    const :name, T.nilable(String), default: nil
+    const :email_address, T.nilable(String), default: nil
+    const :phone_number, T.nilable(String), default: nil
+    const :billing_address, T.nilable(Inttegro::CheckoutOrderCustomerBillingAddress), default: nil
+    const :shipping_address, T.nilable(Inttegro::CheckoutOrderCustomerShippingAddress), default: nil
+  end
+
+  class CheckoutOrderCreatedFrom < T::Struct
+    const :source, T.nilable(String), default: nil
+    const :resource_type, T.nilable(String), default: nil
+    const :resource_id, T.nilable(String), default: nil
+  end
+
+  class CheckoutOrderPaymentPaymentMethod < T::Struct
+    # This object intentionally has no fields.
+  end
+
+  class CheckoutOrderPaymentBillingDetails < T::Struct
+    # This object intentionally has no fields.
+  end
+
+  class CheckoutOrderPaymentLatestAttempt < T::Struct
+    # This object intentionally has no fields.
+  end
+
+  class CheckoutOrderPaymentNextAction < T::Struct
+    # This object intentionally has no fields.
+  end
+
+  class CheckoutOrderPaymentLatestError < T::Struct
+    # This object intentionally has no fields.
+  end
+
+  class CheckoutOrderPayment < T::Struct
+    const :id, T.nilable(String), default: nil
+    const :statement_descriptor, T.nilable(String), default: nil
+    const :payment_method_types, T.nilable(T::Array[String]), default: nil
+    const :payment_method, T.nilable(Inttegro::CheckoutOrderPaymentPaymentMethod), default: nil
+    const :billing_details, T.nilable(Inttegro::CheckoutOrderPaymentBillingDetails), default: nil
+    const :receipt, T.nilable(Inttegro::CheckoutInvoiceView), default: nil
+    const :latest_attempt, T.nilable(Inttegro::CheckoutOrderPaymentLatestAttempt), default: nil
+    const :amount, T.nilable(Inttegro::Amount), default: nil
+    const :next_action, T.nilable(Inttegro::CheckoutOrderPaymentNextAction), default: nil
+    const :latest_error, T.nilable(Inttegro::CheckoutOrderPaymentLatestError), default: nil
+    const :status, T.nilable(String), default: nil
+    const :initiated_at, T.nilable(String), default: nil
+    const :executed_at, T.nilable(String), default: nil
+    const :due_at, T.nilable(String), default: nil
+    const :canceled_at, T.nilable(String), default: nil
+    const :expired_at, T.nilable(String), default: nil
+    const :paid_at, T.nilable(String), default: nil
+    const :paid_offline, T.nilable(T::Boolean), default: nil
+    const :failed_at, T.nilable(String), default: nil
+  end
+
+  class CheckoutOrder < T::Struct
+    const :id, String
+    const :number, T.nilable(String), default: nil
+    const :receipt_number, T.nilable(String), default: nil
+    const :reference, T.nilable(String), default: nil
+    const :status, Inttegro::CheckoutOrderStatus
+    const :initiated_at, String
+    const :sealed_at, T.nilable(String), default: nil
+    const :completed_at, T.nilable(String), default: nil
+    const :paid_at, T.nilable(String), default: nil
+    const :canceled_at, T.nilable(String), default: nil
+    const :expires_at, T.nilable(String), default: nil
+    const :payment_due_at, T.nilable(String), default: nil
+    const :checkout_settings, T.nilable(Inttegro::CheckoutOrderCheckoutSettings), default: nil
+    const :line_item_group, T.nilable(Inttegro::CheckoutOrderLineItemGroup), default: nil
+    const :customer, Inttegro::CheckoutOrderCustomer
+    const :created_from, T.nilable(Inttegro::CheckoutOrderCreatedFrom), default: nil
+    const :payment, T.nilable(Inttegro::CheckoutOrderPayment), default: nil
+    const :invoice, T.nilable(Inttegro::CheckoutInvoiceView), default: nil
+  end
+
+  class CheckoutOrderReferenceRequest < T::Struct
+    const :order_id, String
+  end
+
+  class CheckoutOrderResponse < T::Struct
+    const :order, T.nilable(Inttegro::CheckoutOrder), default: nil
+    const :error, T.nilable(Inttegro::ErrorPayload), default: nil
+  end
+
+  class CheckoutPaymentMethodDataBillingDetails < T::Struct
+    const :name, String
+    const :phone_number, T.nilable(String), default: nil
+    const :address, Inttegro::CheckoutPaymentAddress
+  end
+
+  class CheckoutPayRequestPaymentMethodData < T::Struct
+    const :type, Inttegro::CheckoutPayRequestPaymentMethodDataType
+    const :mobile_money, Inttegro::CheckoutMobileMoneyData
+    const :billing_details, T.nilable(Inttegro::CheckoutPaymentMethodDataBillingDetails), default: nil
+  end
+
+  class CheckoutPayRequest < T::Struct
+    const :order_id, String
+    const :payment_method_id, T.nilable(String), default: nil
+    const :payment_method_data, T.nilable(Inttegro::CheckoutPayRequestPaymentMethodData), default: nil
+    const :save_payment_method, T.nilable(T::Boolean), default: nil
+  end
+
+  class CheckoutPaymentMethodData < T::Struct
+    const :type, Inttegro::CheckoutPaymentMethodDataType
+    const :mobile_money, Inttegro::CheckoutMobileMoneyData
+    const :billing_details, T.nilable(Inttegro::CheckoutPaymentMethodDataBillingDetails), default: nil
+  end
+
   class ChimeRecipientDetailPhone < T::Struct
     const :number, String
   end
@@ -1358,52 +1608,6 @@ module Inttegro
     const :enable_fx, T.nilable(T::Boolean), default: nil
   end
 
-  class InlineProductDetails < T::Struct
-    const :about, T.nilable(String), default: nil
-    const :custom_data, T.nilable(T::Hash[String, Object]), default: nil
-    const :name, String
-    const :price, Inttegro::PriceParams
-    const :quantity, Integer
-    const :reference, T.nilable(String), default: nil
-    const :tax_code, T.nilable(String), default: nil
-    const :type, Inttegro::ProductType
-  end
-
-  ProductDetails = T.type_alias { T.any(Inttegro::InlineProductDetails, Inttegro::CatalogProductWithPriceData, Inttegro::CatalogProductWithPriceReference) }
-
-  class ProductLineItem < T::Struct
-    const :type, Inttegro::ProductLineItemType
-    const :product, Inttegro::ProductDetails
-  end
-
-  class FeeDetails < T::Struct
-    const :id, T.nilable(String), default: nil
-    const :label, T.nilable(String), default: nil
-    const :tax_code, T.nilable(String), default: nil
-    const :description, T.nilable(String), default: nil
-    const :custom_data, T.nilable(T::Hash[String, Object]), default: nil
-    const :amount, Inttegro::AmountParams
-  end
-
-  class FeeLineItem < T::Struct
-    const :type, Inttegro::FeeLineItemType
-    const :fee, Inttegro::FeeDetails
-  end
-
-  class ShippingDetails < T::Struct
-    const :id, T.nilable(String), default: nil
-    const :tax_code, T.nilable(String), default: nil
-    const :custom_data, T.nilable(T::Hash[String, Object]), default: nil
-    const :fee, Inttegro::AmountParams
-  end
-
-  class ShippingLineItem < T::Struct
-    const :type, Inttegro::ShippingLineItemType
-    const :shipping, Inttegro::ShippingDetails
-  end
-
-  LineItem = T.type_alias { T.any(Inttegro::ProductLineItem, Inttegro::FeeLineItem, Inttegro::ShippingLineItem) }
-
   class Shipping < T::Struct
     const :address, Inttegro::Address
   end

data/lib/inttegro/generated/operations.rb

@@ -31,6 +31,10 @@ module Inttegro
       "/customers/lookup" => Inttegro::CustomerResponse,
       "/customers/update" => Inttegro::CustomerResponse,
       "/customers/page" => Inttegro::PageCustomersResponse,
+      "/checkout/lookup" => Inttegro::CheckoutOrderResponse,
+      "/checkout/pay" => Inttegro::CheckoutOrderResponse,
+      "/checkout/confirm_payment" => Inttegro::CheckoutOrderResponse,
+      "/checkout/request_confirmation" => Inttegro::CheckoutOrderResponse,
       "/orders/create" => Inttegro::OrderEnvelope,
       "/orders/lookup" => Inttegro::OrderEnvelope,
       "/orders/update" => Inttegro::OrderEnvelope,
@@ -150,6 +154,10 @@ module Inttegro
       "/customers/lookup" => "Inttegro::LookupCustomerRequest",
       "/customers/update" => "Inttegro::UpdateCustomerRequest",
       "/customers/page" => "Inttegro::PageCustomersRequest",
+      "/checkout/lookup" => "Inttegro::CheckoutOrderReferenceRequest",
+      "/checkout/pay" => "Inttegro::CheckoutPayRequest",
+      "/checkout/confirm_payment" => "Inttegro::CheckoutConfirmPaymentRequest",
+      "/checkout/request_confirmation" => "Inttegro::CheckoutOrderReferenceRequest",
       "/orders/create" => "T.any(Inttegro::CreateOrderNewCustomer, Inttegro::CreateOrderExistingCustomer)",
       "/orders/lookup" => "Inttegro::LookupOrderRequest",
       "/orders/update" => "Inttegro::UpdateOrderRequest",
@@ -267,6 +275,10 @@ module Inttegro
       "/customers/lookup" => "lookupCustomer",
       "/customers/update" => "updateCustomer",
       "/customers/page" => "pageCustomers",
+      "/checkout/lookup" => "lookupCheckoutOrder",
+      "/checkout/pay" => "payCheckoutOrder",
+      "/checkout/confirm_payment" => "confirmCheckoutPayment",
+      "/checkout/request_confirmation" => "requestCheckoutConfirmation",
       "/orders/create" => "createOrder",
       "/orders/lookup" => "lookupOrder",
       "/orders/update" => "updateOrder",

data/lib/inttegro/http_client.rb

@@ -12,6 +12,7 @@ require_relative "models"
 require_relative "generated/operations"
 require_relative "response_object"
 require_relative "transport_response"
+require_relative "telemetry"
 require_relative "types"
 require_relative "version"
 
@@ -34,10 +35,20 @@ module Inttegro
         base_url: T.nilable(String),
         read_timeout: T.nilable(Numeric),
         open_timeout: T.nilable(Numeric),
-        adapter: T.nilable(Types::Adapter)
+        adapter: T.nilable(Types::Adapter),
+        telemetry_enabled: T::Boolean,
+        tracer_provider: T.nilable(OpenTelemetry::Trace::TracerProvider)
       ).void
     end
-    def initialize(api_key:, base_url: DEFAULT_BASE_URL, read_timeout: 30, open_timeout: 10, adapter: nil)
+    def initialize(
+      api_key:,
+      base_url: DEFAULT_BASE_URL,
+      read_timeout: 30,
+      open_timeout: 10,
+      adapter: nil,
+      telemetry_enabled: true,
+      tracer_provider: nil
+    )
       @api_key = T.let(api_key || "", String)
       raise ArgumentError, "api_key is required" if @api_key.strip.empty?
 
@@ -48,6 +59,10 @@ module Inttegro
       @read_timeout = T.let(read_timeout, T.nilable(Numeric))
       @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
+      )
     end
 
     sig { params(path: String, headers: Types::Headers, query: T.nilable(Types::Query)).returns(ResponseValue) }
@@ -165,16 +180,17 @@ module Inttegro
           fields: Types::Payload,
           files: Types::Payload,
           headers: Types::Headers,
-          authenticated: T::Boolean
+          authenticated: T::Boolean,
+          operation: T.nilable(String)
         )
         .returns(T.type_parameter(:Model))
     end
-    def post_multipart_model(path, model, fields: {}, files: {}, headers: {}, authenticated: true)
+    def post_multipart_model(path, model, fields: {}, files: {}, headers: {}, authenticated: true, operation: nil)
       unless model <= T::Struct
         raise TypeError, "response model for #{path} must inherit from T::Struct"
       end
 
-      response = perform_multipart(path, fields, files, headers, authenticated, model)
+      response = perform_multipart(path, fields, files, headers, authenticated, model, operation)
       return T.cast(response, T.type_parameter(:Model)) if response.is_a?(model)
 
       raise TypeError, "expected #{model} from #{path}, got #{response.class}"
@@ -218,62 +234,76 @@ module Inttegro
         files: Types::Payload,
         headers: Types::Headers,
         authenticated: T::Boolean,
-        model: T.nilable(T::Class[T::Struct])
+        model: T.nilable(T::Class[T::Struct]),
+        operation: T.nilable(String)
       ).returns(ResponseValue)
     end
-    def perform_multipart(path, fields, files, headers, authenticated, model)
-      uri = build_uri(path, nil)
-      request = Net::HTTP::Post.new(uri)
-      request["Accept"] = "application/json"
-      request["User-Agent"] = USER_AGENT
-      request["Authorization"] = "Bearer #{@api_key}" if authenticated
-      headers = headers.dup
-      if authenticated && idempotent_mutation_path?(path) && !header_present?(headers, "Idempotency-Key")
-        headers["Idempotency-Key"] = generate_idempotency_key
-      end
-      headers.each { |key, value| request[key] = value }
+    def perform_multipart(path, fields, files, headers, authenticated, model, operation = nil)
+      @telemetry.in_span(path, :post, @base_url, Inttegro::VERSION, operation) do |span|
+        uri = build_uri(path, nil)
+        request = Net::HTTP::Post.new(uri)
+        request["Accept"] = "application/json"
+        request["User-Agent"] = USER_AGENT
+        request["Authorization"] = "Bearer #{@api_key}" if authenticated
+        headers = headers.dup
+        if authenticated && idempotent_mutation_path?(path) && !header_present?(headers, "Idempotency-Key")
+          headers["Idempotency-Key"] = generate_idempotency_key
+        end
+        headers.each { |key, value| request[key] = value }
 
-      form = []
-      fields.each do |key, value|
-        next if value.nil?
+        form = []
+        fields.each do |key, value|
+          next if value.nil?
 
-        form << [key.to_s, value.is_a?(Hash) || value.is_a?(Array) ? JSON.generate(value) : value.to_s]
-      end
-      files.each do |key, path|
-        raise ArgumentError, "file path for #{key} must be a String" unless path.is_a?(String)
+          form << [key.to_s, value.is_a?(Hash) || value.is_a?(Array) ? JSON.generate(value) : value.to_s]
+        end
+        files.each do |key, file_path|
+          raise ArgumentError, "file path for #{key} must be a String" unless file_path.is_a?(String)
 
-        form << [key.to_s, File.open(path)]
+          form << [key.to_s, File.open(file_path)]
+        end
+        request.set_form(form, "multipart/form-data")
+        @telemetry.prepare(span, request)
+
+        raw_response = @adapter ? @adapter.call(uri, request) : build_http(uri).request(request)
+        response = TransportResponse.new(raw_response)
+        @telemetry.response(span, response, decoded: false)
+        result = handle_response(path, response, model)
+        @telemetry.decoded(span)
+        result
       end
-      request.set_form(form, "multipart/form-data")
-
-      raw_response = @adapter ? @adapter.call(uri, request) : build_http(uri).request(request)
-      response = TransportResponse.new(raw_response)
-      handle_response(path, response, model)
     end
 
     sig { params(path: String, body: Types::RequestBody).returns(FileDownload) }
     def post_binary_json(path, body)
-      body = with_request_meta_idempotency(:post, path, coerce_body(body), {})
-      response = raw_request(:post, path, JSON.dump(body), {
-        "Accept" => "application/octet-stream",
-        "Content-Type" => "application/json",
-        "Authorization" => "Bearer #{@api_key}"
-      })
-      return FileDownload.new(response.body, response.headers) if response.code.to_i < 400
-
-      raise_response_error(response)
+      @telemetry.in_span(path, :post, @base_url, Inttegro::VERSION) do |span|
+        payload = with_request_meta_idempotency(:post, path, coerce_body(body), {})
+        response = raw_request(:post, path, JSON.dump(payload), {
+          "Accept" => "application/octet-stream",
+          "Content-Type" => "application/json",
+          "Authorization" => "Bearer #{@api_key}"
+        }, span)
+        @telemetry.response(span, response, decoded: false)
+        return FileDownload.new(response.body, response.headers) if response.code.to_i < 400
+
+        raise_response_error(response)
+      end
     end
 
     sig { params(url: String).returns(FileDownload) }
     def get_binary_public(url)
-      uri = build_uri(url, nil)
-      request = Net::HTTP::Get.new(uri)
-      request["User-Agent"] = USER_AGENT
-      raw_response = @adapter ? @adapter.call(uri, request) : build_http(uri).request(request)
-      response = TransportResponse.new(raw_response)
-      return FileDownload.new(response.body, response.headers) if response.code.to_i < 400
-
-      raise_response_error(response)
+      @telemetry.in_span(url, :get, @base_url, Inttegro::VERSION, "file_links.download") do |span|
+        uri = build_uri(url, nil)
+        request = Net::HTTP::Get.new(uri)
+        request["User-Agent"] = USER_AGENT
+        @telemetry.prepare(span, request)
+        raw_response = @adapter ? @adapter.call(uri, request) : build_http(uri).request(request)
+        response = TransportResponse.new(raw_response)
+        @telemetry.response(span, response, decoded: false)
+        return FileDownload.new(response.body, response.headers) if response.code.to_i < 400
+
+        raise_response_error(response)
+      end
     end
 
     sig do
@@ -287,20 +317,26 @@ module Inttegro
       ).returns(ResponseValue)
     end
     def request(method, path, body: nil, headers: {}, query: nil, response_model: nil)
-      uri = build_uri(path, query)
-      body = validate_body(path, coerce_body(body))
-      body = with_request_meta_idempotency(method, path, body, headers)
-      request = build_request(method, uri, body, headers)
-
-      raw_response =
-        if @adapter
-          @adapter.call(uri, request)
-        else
-          http = build_http(uri)
-          http.request(request)
-        end
-      response = TransportResponse.new(raw_response)
-      handle_response(path, response, response_model)
+      @telemetry.in_span(path, method, @base_url, Inttegro::VERSION) do |span|
+        uri = build_uri(path, query)
+        body = validate_body(path, coerce_body(body))
+        body = with_request_meta_idempotency(method, path, body, headers)
+        request = build_request(method, uri, body, headers)
+        @telemetry.prepare(span, request)
+
+        raw_response =
+          if @adapter
+            @adapter.call(uri, request)
+          else
+            http = build_http(uri)
+            http.request(request)
+          end
+        response = TransportResponse.new(raw_response)
+        @telemetry.response(span, response, decoded: false)
+        result = handle_response(path, response, response_model)
+        @telemetry.decoded(span)
+        result
+      end
     rescue Timeout::Error, Errno::ETIMEDOUT => e
       raise TimeoutError.new("Request timed out", e)
     rescue SocketError, Errno::ECONNREFUSED, Errno::ECONNRESET => e
@@ -327,13 +363,15 @@ module Inttegro
         method: T.any(String, Symbol),
         path: String,
         body: T.nilable(String),
-        headers: Types::Headers
+        headers: Types::Headers,
+        span: T.nilable(OpenTelemetry::Trace::Span)
       ).returns(TransportResponse)
     end
-    def raw_request(method, path, body, headers)
+    def raw_request(method, path, body, headers, span = nil)
       uri = build_uri(path, nil)
       request = build_request(method, uri, nil, headers)
       request.body = body if body
+      @telemetry.prepare(span, request)
       raw_response = @adapter ? @adapter.call(uri, request) : build_http(uri).request(request)
       TransportResponse.new(raw_response)
     end

data/lib/inttegro/resources/upload_requests.rb

@@ -52,7 +52,8 @@ module Inttegro
           upload_url,
           Inttegro::UploadFulfillment,
           files: { file: file },
-          authenticated: false
+          authenticated: false,
+          operation: "upload_requests.upload"
         )
       end
 

data/lib/inttegro/telemetry.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+# typed: strict
+
+require "opentelemetry-api"
+require "sorbet-runtime"
+require "uri"
+
+require_relative "errors"
+
+module Inttegro
+  # Emits redacted SDK spans to the application's OpenTelemetry provider.
+  # This class never configures an exporter or sends telemetry to Inttegro.
+  class Telemetry
+    extend T::Sig
+
+    SAFE_RESOURCES = %w[
+      apps balance_transactions balances broadcasts checkout chimes customers file_links file_references files
+      financial_accounts keys message_templates orders otp payment_methods payouts ping prices products
+      purchase_intents refunds schedules sessions spec upload_requests
+    ].freeze
+    SAFE_ACTIONS = %w[
+      activate add_price archive broadcast cancel complete confirm_payment confirm_verification connect contents
+      countries create deactivate delete destroy disable disable_fx disable_pull disable_push disactivate disconnect
+      enable enable_fx enable_pull enable_push finalize generate initiate lookup new open page pay publish reconcile
+      reconnect refund render_preview request_confirmation review revoke schedule send send_invoice send_receipt
+      set_default_unit_price set_destinations settings tokenize unarchive unpublish update upload usage verify
+    ].freeze
+
+    sig do
+      params(
+        version: String,
+        enabled: T::Boolean,
+        tracer_provider: T.nilable(OpenTelemetry::Trace::TracerProvider)
+      ).void
+    end
+    def initialize(version, enabled: true, tracer_provider: nil)
+      @enabled = T.let(enabled, T::Boolean)
+      provider = tracer_provider || OpenTelemetry.tracer_provider
+      @tracer = T.let(provider.tracer("inttegro", version), OpenTelemetry::Trace::Tracer)
+    end
+
+    sig do
+      type_parameters(:Result)
+        .params(
+          path_or_url: String,
+          method: T.any(String, Symbol),
+          base_url: String,
+          version: String,
+          operation_override: T.nilable(String),
+          block: T.proc.params(span: T.nilable(OpenTelemetry::Trace::Span)).returns(T.type_parameter(:Result))
+        )
+        .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
+
+      operation, route, server_address = request_details(path_or_url, base_url, operation_override)
+      attributes = {
+        "inttegro.operation.name" => operation,
+        "inttegro.sdk.language" => "ruby",
+        "inttegro.sdk.version" => version,
+        "http.request.method" => method.to_s.upcase,
+        "server.address" => server_address
+      }
+      attributes["url.template"] = route if route
+      span = @tracer.start_span("inttegro.#{operation}", kind: :client, attributes: attributes)
+
+      begin
+        OpenTelemetry::Trace.with_span(span) { |_active_span, _context| yield(span) }
+      rescue StandardError => e
+        error_type = classify_error(e)
+        span.set_attribute("error.type", error_type)
+        span.status = OpenTelemetry::Trace::Status.error
+        span.add_event("inttegro.request.failed", attributes: { "error.type" => error_type })
+        raise
+      ensure
+        span.finish
+      end
+    end
+
+    sig { params(span: T.nilable(OpenTelemetry::Trace::Span), request: Net::HTTPRequest).void }
+    def prepare(span, request)
+      if @enabled
+        carrier = T.let({}, T::Hash[String, String])
+        OpenTelemetry.propagation.inject(carrier)
+        carrier.each { |key, value| request[key] = value unless request[key] }
+      end
+      return unless span
+
+      span.add_event("inttegro.request.prepared")
+      span.add_event(
+        "inttegro.http.attempt.started",
+        attributes: { "http.request.resend_count" => 0 }
+      )
+    end
+
+    sig do
+      params(
+        span: T.nilable(OpenTelemetry::Trace::Span),
+        response: TransportResponse,
+        decoded: T::Boolean
+      ).void
+    end
+    def response(span, response, decoded:)
+      return unless span
+
+      status = response.code.to_i
+      span.set_attribute("http.response.status_code", status)
+      request_id = response["x-request-id"]
+      span.set_attribute("inttegro.request.id", request_id) if request_id && !request_id.empty?
+      span.add_event(
+        "inttegro.response.received",
+        attributes: {
+          "http.response.status_code" => status,
+          "http.request.resend_count" => 0
+        }
+      )
+      span.add_event("inttegro.response.decoded") if decoded
+    end
+
+    sig { params(span: T.nilable(OpenTelemetry::Trace::Span)).void }
+    def decoded(span)
+      span.add_event("inttegro.response.decoded") if span
+    end
+
+    private
+
+    sig do
+      params(path_or_url: String, base_url: String, override: T.nilable(String))
+        .returns([String, T.nilable(String), String])
+    end
+    def request_details(path_or_url, base_url, override)
+      uri = path_or_url.start_with?("http://", "https://") ? URI.parse(path_or_url) : URI.join("#{base_url}/", path_or_url.sub(%r{\A/}, ""))
+      segments = path_or_url.start_with?("http://", "https://") ? [] : T.must(uri.path).split("/").reject(&:empty?)
+      resource = segments[0]
+      action = segments[1]
+      known_route = !resource.nil? && segments.length <= 2 && SAFE_RESOURCES.include?(resource) &&
+        (action.nil? || SAFE_ACTIONS.include?(action))
+      route = known_route ? uri.path : nil
+      derived_operation = known_route ? "#{resource}.#{action || (resource == 'balances' ? 'lookup' : 'request')}" : "http.request"
+      [override || derived_operation, route, uri.host || "unknown"]
+    end
+
+    sig { params(error: StandardError).returns(String) }
+    def classify_error(error)
+      return "timeout" if error.is_a?(TimeoutError) || error.is_a?(Timeout::Error) || error.is_a?(Errno::ETIMEDOUT)
+      return "network_error" if error.is_a?(NetworkError) || error.is_a?(SocketError) || error.is_a?(SystemCallError)
+      return "http_#{error.status}" if error.is_a?(APIError)
+      return "decode_error" if error.is_a?(JSON::ParserError)
+
+      "unknown_error"
+    end
+  end
+
+  private_constant :Telemetry
+end

data/lib/inttegro/version.rb

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

data/rbi/opentelemetry-api.rbi

@@ -0,0 +1,77 @@
+# typed: strict
+
+# Minimal signatures for the opentelemetry-api surface used by this SDK.
+module OpenTelemetry
+  sig { returns(Trace::TracerProvider) }
+  def self.tracer_provider; end
+
+  sig { returns(Context::Propagation::TextMapPropagator) }
+  def self.propagation; end
+
+  class Context
+    module Propagation
+      class TextMapPropagator
+        sig { params(carrier: T::Hash[String, String]).void }
+        def inject(carrier); end
+      end
+    end
+  end
+
+  module Trace
+    sig do
+      type_parameters(:Result)
+        .params(
+          span: Span,
+          block: T.proc.params(span: Span, context: OpenTelemetry::Context).returns(T.type_parameter(:Result))
+        )
+        .returns(T.type_parameter(:Result))
+    end
+    def self.with_span(span, &block); end
+
+    class TracerProvider
+      sig do
+        params(
+          deprecated_name: T.nilable(String),
+          deprecated_version: T.nilable(String),
+          name: T.nilable(String),
+          version: T.nilable(String),
+          attributes: T.nilable(Object)
+        ).returns(Tracer)
+      end
+      def tracer(deprecated_name = nil, deprecated_version = nil, name: nil, version: nil, attributes: nil); end
+    end
+
+    class Tracer
+      sig do
+        params(
+          name: String,
+          with_parent: T.nilable(Object),
+          attributes: T.nilable(Object),
+          links: T.nilable(Object),
+          start_timestamp: T.nilable(Time),
+          kind: T.nilable(Symbol)
+        ).returns(Span)
+      end
+      def start_span(name, with_parent: nil, attributes: nil, links: nil, start_timestamp: nil, kind: nil); end
+    end
+
+    class Span
+      sig { params(key: String, value: Object).returns(Span) }
+      def set_attribute(key, value); end
+
+      sig { params(name: String, attributes: T.nilable(Object), timestamp: T.nilable(Time)).returns(Span) }
+      def add_event(name, attributes: nil, timestamp: nil); end
+
+      sig { params(status: Status).void }
+      def status=(status); end
+
+      sig { void }
+      def finish; end
+    end
+
+    class Status
+      sig { params(description: String).returns(Status) }
+      def self.error(description = ""); end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: inttegro
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 4.2.1
 platform: ruby
 authors:
 - Inttegro Engineering
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-03 00:00:00.000000000 Z
+date: 2026-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 description: First-party Ruby client for working with orders, payments, payouts, notifications,
   and verification on Inttegro.
 email:
@@ -73,10 +87,12 @@ files:
 - lib/inttegro/resources/spec.rb
 - lib/inttegro/resources/upload_requests.rb
 - lib/inttegro/response_object.rb
+- lib/inttegro/telemetry.rb
 - lib/inttegro/transport_response.rb
 - lib/inttegro/types.rb
 - lib/inttegro/version.rb
 - rbi/inttegro/generated.rbi
+- rbi/opentelemetry-api.rbi
 homepage: https://studio.inttegro.com
 licenses:
 - MIT