inttegro 4.3.1 → 6.0.0

data/lib/inttegro/resources/payouts.rb

@@ -11,6 +11,7 @@ module Inttegro
     #
     # @see https://studio.inttegro.com/payouts for detailed guides
     class Payouts
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
@@ -23,7 +24,7 @@ module Inttegro
       #
       # @param destinations [Hash] Map of currency codes to financial account IDs (required)
       #
-      # @return [Inttegro::PayoutSettingsMutation] Updated payout settings
+      # @return [Inttegro::Payout::SettingsMutation] Updated payout settings
       #
       # @example Set payout destinations for multiple currencies
       #   result = client.payouts.set_destinations(
@@ -39,7 +40,7 @@ module Inttegro
       def set_destinations(destinations:)
         @http.post_resource(
           "/payouts/set_destinations",
-          Inttegro::PayoutSettingsMutation, :settings,
+          Inttegro::Payout::SettingsMutation, :settings,
           { destinations: destinations }
         )
       end
@@ -49,7 +50,7 @@ module Inttegro
       # Returns payout settings including configured payout destinations, schedule information,
       # and whether foreign exchange is enabled.
       #
-      # @return [Inttegro::PayoutSettingsLookup] Current payout settings
+      # @return [Inttegro::Payout::SettingsLookup] Current payout settings
       #
       # @example Get payout settings
       #   result = client.payouts.settings
@@ -58,7 +59,7 @@ module Inttegro
       #
       # @see https://studio.inttegro.com/product-payouts for payouts overview
       def settings
-        @http.post_resource("/payouts/settings", Inttegro::PayoutSettingsLookup, :settings, {})
+        @http.post_resource("/payouts/settings", Inttegro::Payout::SettingsLookup, :settings, {})
       end
 
       # Disable automatic payouts by switching to manual payout mode.
@@ -68,7 +69,7 @@ module Inttegro
       # still be at least 7 days old before they can be paid out, but the payout will only occur when you
       # explicitly request it.
       #
-      # @return [Inttegro::PayoutSettingsMutation] Updated payout settings
+      # @return [Inttegro::Payout::SettingsMutation] Updated payout settings
       #
       # @example Disable automatic payouts
       #   result = client.payouts.disable_automatic
@@ -79,15 +80,18 @@ module Inttegro
       def disable_automatic
         @http.post_resource(
           "/payouts/disable",
-          Inttegro::PayoutSettingsMutation, :settings,
+          Inttegro::Payout::SettingsMutation, :settings,
           {}
         )
       end
 
+      # Re-enable automatic payouts using the application's retained schedule settings.
+      #
+      # @return [Inttegro::Payout::SettingsMutation] updated payout settings
       def enable_automatic
         @http.post_resource(
           "/payouts/enable",
-          Inttegro::PayoutSettingsMutation, :settings,
+          Inttegro::Payout::SettingsMutation, :settings,
           {}
         )
       end
@@ -106,7 +110,7 @@ module Inttegro
       # Important: FX conversion incurs additional fees beyond standard payout fees, and exchange rates are
       # determined at payout execution time. FX-enabled payouts require approval and special configuration.
       #
-      # @return [Inttegro::PayoutSettingsLookup] Updated payout settings
+      # @return [Inttegro::Payout::SettingsLookup] Updated payout settings
       #
       # @example Enable foreign exchange for payouts
       #   result = client.payouts.enable_fx
@@ -115,7 +119,7 @@ module Inttegro
       #
       # @see https://studio.inttegro.com/enable-fx-payouts for FX payout guide
       def enable_fx
-        @http.post_resource("/payouts/enable_fx", Inttegro::PayoutSettingsLookup, :settings, {})
+        @http.post_resource("/payouts/enable_fx", Inttegro::Payout::SettingsLookup, :settings, {})
       end
 
       # Disable foreign exchange conversion for payouts.
@@ -123,7 +127,7 @@ module Inttegro
       # Disables FX conversion, restricting payouts to accounts that match the transaction currency.
       # After disabling FX, GHS balance can only be paid out to GHS accounts, USD balance only to USD accounts, etc.
       #
-      # @return [Inttegro::PayoutSettingsLookup] Updated payout settings
+      # @return [Inttegro::Payout::SettingsLookup] Updated payout settings
       #
       # @example Disable foreign exchange for payouts
       #   result = client.payouts.disable_fx
@@ -132,7 +136,7 @@ module Inttegro
       #
       # @see https://studio.inttegro.com/disable-fx-payouts for FX payout guide
       def disable_fx
-        @http.post_resource("/payouts/disable_fx", Inttegro::PayoutSettingsLookup, :settings, {})
+        @http.post_resource("/payouts/disable_fx", Inttegro::Payout::SettingsLookup, :settings, {})
       end
 
       # Retrieve a paginated list of payouts.
@@ -140,14 +144,14 @@ module Inttegro
       # Returns payouts in reverse chronological order (most recent first). Use the has_more field
       # and page parameter to navigate through results. Supports filtering by status and time range.
       #
-      # @param payload [Hash] Pagination and filter parameters (optional)
+      # @param payload [Hash, Inttegro::Payout::PageRequest] Pagination and filter parameters (optional)
       # @option payload [Integer] :page Page number to retrieve (minimum 1, default: 1)
       # @option payload [Integer] :per_page Number of results per page (minimum 1, maximum 100, default: 10)
       # @option payload [String] :status Filter by payout status (e.g., 'pending', 'paid', 'failed')
-      # @option payload [String] :created_after Filter payouts created after this timestamp (ISO 8601)
-      # @option payload [String] :created_before Filter payouts created before this timestamp (ISO 8601)
+      # @option payload [Time] :created_after Filter payouts created after this timestamp
+      # @option payload [Time] :created_before Filter payouts created before this timestamp
       #
-      # @return [Inttegro::PayoutPage] Paginated list of payouts
+      # @return [Inttegro::Payout::Page] Paginated list of payouts
       #
       # @example Get first page of payouts
       #   result = client.payouts.page(
@@ -166,13 +170,21 @@ module Inttegro
       # @see https://studio.inttegro.com/pagination for pagination guide
       # @see https://studio.inttegro.com/product-payouts for payouts overview
       def page(payload = {})
-        @http.post_resource("/payouts/page", Inttegro::PayoutPage, :page, payload || {})
+        @http.post_resource("/payouts/page", Inttegro::Payout::Page, :page, payload || {})
       end
 
+      # Schedule a payout from the application's available balance.
+      #
+      # @param payload [Hash, Inttegro::Schedule::PayoutRequest] amount, destination, and execution fields
+      # @return [Inttegro::Payout] scheduled payout
       def schedule(payload)
         @http.post_resource("/payouts/schedule", Inttegro::Payout, :payout, payload)
       end
 
+      # Retrieve the current state of one payout.
+      #
+      # @param payout_id [String] unique payout identifier
+      # @return [Inttegro::Payout] matching payout
       def lookup(payout_id:)
         @http.post_resource(
           "/payouts/lookup",

data/lib/inttegro/resources/prices.rb

@@ -3,37 +3,69 @@
 
 module Inttegro
   module Resources
+    # Client for catalog prices and their lifecycle.
+    #
+    # Access this resource through {Inttegro::Client#prices}.
     class Prices
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
 
+      # Create a catalog price.
+      #
+      # @param payload [Hash, Inttegro::Price::CatalogPriceParams] amount and optional price metadata
+      # @return [Inttegro::Price::CatalogPrice] created price
       def create(payload)
-        @http.post_resource("/prices/create", Inttegro::CatalogPrice, :price, payload)
+        @http.post_resource("/prices/create", Inttegro::Price::CatalogPrice, :price, payload)
       end
 
+      # Retrieve one catalog price.
+      #
+      # @param price_id [String] unique price identifier
+      # @return [Inttegro::Price::CatalogPrice] matching price
       def lookup(price_id:)
-        @http.post_resource("/prices/lookup", Inttegro::CatalogPrice, :price, { price_id: price_id })
+        @http.post_resource("/prices/lookup", Inttegro::Price::CatalogPrice, :price, { price_id: price_id })
       end
 
+      # Retrieve a page of catalog prices.
+      #
+      # @param payload [Hash, Inttegro::Price::PageRequest] pagination and filter fields
+      # @return [Inttegro::Price::Page] typed page of prices
       def page(payload = {})
-        @http.post_resource("/prices/page", Inttegro::PricePage, :page, payload || {})
+        @http.post_resource("/prices/page", Inttegro::Price::Page, :page, payload || {})
       end
 
+      # Update mutable price metadata.
+      #
+      # @param payload [Hash, Inttegro::Price::UpdateRequest] price identifier and fields to change
+      # @return [Inttegro::Price::CatalogPrice] updated price
       def update(payload)
-        @http.post_resource("/prices/update", Inttegro::CatalogPrice, :price, payload)
+        @http.post_resource("/prices/update", Inttegro::Price::CatalogPrice, :price, payload)
       end
 
+      # Reactivate an inactive price.
+      #
+      # @param price_id [String] unique price identifier
+      # @return [Inttegro::Price::CatalogPrice] activated price
       def activate(price_id:)
-        @http.post_resource("/prices/activate", Inttegro::CatalogPrice, :price, { price_id: price_id })
+        @http.post_resource("/prices/activate", Inttegro::Price::CatalogPrice, :price, { price_id: price_id })
       end
 
+      # Deactivate a price for new active catalog flows.
+      #
+      # @param price_id [String] unique price identifier
+      # @return [Inttegro::Price::CatalogPrice] deactivated price
       def deactivate(price_id:)
-        @http.post_resource("/prices/deactivate", Inttegro::CatalogPrice, :price, { price_id: price_id })
+        @http.post_resource("/prices/deactivate", Inttegro::Price::CatalogPrice, :price, { price_id: price_id })
       end
 
+      # Archive a price and mark it inactive.
+      #
+      # @param price_id [String] unique price identifier
+      # @return [Inttegro::Price::CatalogPrice] archived price
       def archive(price_id:)
-        @http.post_resource("/prices/archive", Inttegro::CatalogPrice, :price, { price_id: price_id })
+        @http.post_resource("/prices/archive", Inttegro::Price::CatalogPrice, :price, { price_id: price_id })
       end
     end
   end

data/lib/inttegro/resources/products.rb

@@ -3,45 +3,85 @@
 
 module Inttegro
   module Resources
+    # Client for products and their catalog lifecycle.
+    #
+    # Access this resource through {Inttegro::Client#products}.
     class Products
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
 
+      # Create a catalog product.
+      #
+      # @param payload [Hash, Inttegro::Product::CreateRequest] product fields
+      # @return [Inttegro::Product] created product
       def create(payload)
         @http.post_resource("/products/create", Inttegro::Product, :product, payload)
       end
 
+      # Create a new price for an existing product.
+      #
+      # @param payload [Hash, Inttegro::Product::AddPriceRequest] product identifier and price fields
+      # @return [Inttegro::Price::CatalogPrice] created price
       def add_price(payload)
-        @http.post_resource("/products/add_price", Inttegro::CatalogPrice, :price, payload)
+        @http.post_resource("/products/add_price", Inttegro::Price::CatalogPrice, :price, payload)
       end
 
+      # Select an existing catalog price as the product's default unit price.
+      #
+      # @param payload [Hash, Inttegro::Product::SetDefaultUnitPriceRequest] product and price identifiers
+      # @return [Inttegro::Product] updated product
       def set_default_unit_price(payload)
         @http.post_resource("/products/set_default_unit_price", Inttegro::Product, :product, payload)
       end
 
+      # Retrieve a product and its related catalog details.
+      #
+      # @param product_id [String] unique product identifier
+      # @return [Inttegro::Product] matching product
       def lookup(product_id:)
         @http.post_resource("/products/lookup", Inttegro::Product, :product, { product_id: product_id })
       end
 
+      # Update mutable product fields.
+      #
+      # @param payload [Hash, Inttegro::Product::UpdateRequest] product identifier and fields to change
+      # @return [Inttegro::Product::Updated] updated product representation
       def update(payload)
-        @http.post_resource("/products/update", Inttegro::UpdatedProduct, :product, payload)
+        @http.post_resource("/products/update", Inttegro::Product::Updated, :product, payload)
       end
 
+      # Mark a product active and record its publication time.
+      #
+      # @param product_id [String] unique product identifier
+      # @return [Inttegro::Product] published product
       def publish(product_id:)
         @http.post_resource("/products/publish", Inttegro::Product, :product, { product_id: product_id })
       end
 
+      # Mark a product inactive without archiving it.
+      #
+      # @param product_id [String] unique product identifier
+      # @return [Inttegro::Product] unpublished product
       def unpublish(product_id:)
         @http.post_resource("/products/unpublish", Inttegro::Product, :product, { product_id: product_id })
       end
 
+      # Archive a product and mark it inactive.
+      #
+      # @param product_id [String] unique product identifier
+      # @return [Inttegro::Product] archived product
       def archive(product_id:)
         @http.post_resource("/products/archive", Inttegro::Product, :product, { product_id: product_id })
       end
 
+      # Retrieve a page of products.
+      #
+      # @param payload [Hash, Inttegro::Product::PageRequest] pagination fields
+      # @return [Inttegro::Product::Page] typed page of products
       def page(payload = {})
-        @http.post_resource("/products/page", Inttegro::ProductPage, :page, payload || {})
+        @http.post_resource("/products/page", Inttegro::Product::Page, :page, payload || {})
       end
     end
   end

data/lib/inttegro/resources/purchase_intents.rb

@@ -3,19 +3,35 @@
 
 module Inttegro
   module Resources
+    # Client for controlled, shareable purchase intents and hosted Buy links.
+    #
+    # Access this resource through {Inttegro::Client#purchase_intents}.
     class PurchaseIntents
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
 
+      # Create a purchase intent for a catalog product.
+      #
+      # @param payload [Hash, Inttegro::PurchaseIntent::CreateRequest] offer, quantity, and usage fields
+      # @return [Inttegro::PurchaseIntent] created purchase intent
       def create(payload)
         @http.post_resource("/purchase_intents/create", Inttegro::PurchaseIntent, :purchase_intent, payload)
       end
 
+      # Change mutable quantity or expiry fields on a purchase intent.
+      #
+      # @param payload [Hash, Inttegro::PurchaseIntent::UpdateRequest] purchase intent identifier and changes
+      # @return [Inttegro::PurchaseIntent] updated purchase intent
       def update(payload)
         @http.post_resource("/purchase_intents/update", Inttegro::PurchaseIntent, :purchase_intent, payload)
       end
 
+      # Stop a purchase intent from creating new orders.
+      #
+      # @param id [String] unique purchase intent identifier
+      # @return [Inttegro::PurchaseIntent] canceled purchase intent
       def cancel(id:)
         @http.post_resource(
           "/purchase_intents/cancel",
@@ -24,6 +40,10 @@ module Inttegro
         )
       end
 
+      # Retrieve a purchase intent by its opaque identifier.
+      #
+      # @param id [String] unique purchase intent identifier
+      # @return [Inttegro::PurchaseIntent] matching purchase intent
       def lookup(id:)
         @http.post_resource(
           "/purchase_intents/lookup",
@@ -32,10 +52,14 @@ module Inttegro
         )
       end
 
+      # Retrieve purchase intents in newest-first order.
+      #
+      # @param payload [Hash, Inttegro::PurchaseIntent::PageRequest] pagination and filter fields
+      # @return [Inttegro::PurchaseIntent::Page] typed page of purchase intents
       def page(payload = {})
         @http.post_resource(
           "/purchase_intents/page",
-          Inttegro::PurchaseIntentPage, :page,
+          Inttegro::PurchaseIntent::Page, :page,
           payload || {}
         )
       end

data/lib/inttegro/resources/refunds.rb

@@ -3,15 +3,27 @@
 
 module Inttegro
   module Resources
+    # Client for creating, canceling, and observing refunds.
+    #
+    # Access this resource through {Inttegro::Client#refunds}.
     class Refunds
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
 
+      # Start a refund for paid order line items.
+      #
+      # @param payload [Hash, Inttegro::Refund::CreateRequest] order, line items, and refund reason
+      # @return [Inttegro::Refund] created refund
       def create(payload)
         @http.post_resource("/refunds/create", Inttegro::Refund, :refund, payload)
       end
 
+      # Cancel a pending refund before processing claims it.
+      #
+      # @param refund_id [String] unique refund identifier
+      # @return [Inttegro::Refund] canceled refund
       def cancel(refund_id:)
         @http.post_resource(
           "/refunds/cancel",
@@ -20,6 +32,10 @@ module Inttegro
         )
       end
 
+      # Retrieve the current lifecycle state and amounts for one refund.
+      #
+      # @param refund_id [String] unique refund identifier
+      # @return [Inttegro::Refund] matching refund
       def lookup(refund_id:)
         @http.post_resource(
           "/refunds/lookup",
@@ -28,8 +44,12 @@ module Inttegro
         )
       end
 
+      # Retrieve a page of refunds.
+      #
+      # @param payload [Hash, Inttegro::Refund::PageRequest] pagination and filter fields
+      # @return [Inttegro::Refund::Page] typed page of refunds
       def page(payload)
-        @http.post_resource("/refunds/page", Inttegro::RefundPage, :page, payload)
+        @http.post_resource("/refunds/page", Inttegro::Refund::Page, :page, payload)
       end
     end
   end

data/lib/inttegro/resources/schedules.rb

@@ -3,23 +3,35 @@
 
 module Inttegro
   module Resources
+    # Client for observing and canceling scheduled Chimes.
+    #
+    # Access this resource through {Inttegro::Client#schedules}.
     class Schedules
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
 
+      # Retrieve one scheduled Chime.
+      #
+      # @param schedule_id [String] unique schedule identifier
+      # @return [Inttegro::Schedule::Detail] schedule details
       def lookup(schedule_id:)
         @http.post_resource(
           "/schedules/lookup",
-          Inttegro::ScheduleDetail, :scheduled_chime,
+          Inttegro::Schedule::Detail, :scheduled_chime,
           { schedule_id: schedule_id }
         )
       end
 
+      # Request cancellation of a Chime schedule that has not won its execution race.
+      #
+      # @param schedule_id [String] unique schedule identifier
+      # @return [Inttegro::Schedule::CancelDetail] resulting cancellation details
       def cancel(schedule_id:)
         @http.post_resource(
           "/schedules/cancel",
-          Inttegro::ScheduleCancelDetail, :scheduled_chime,
+          Inttegro::Schedule::CancelDetail, :scheduled_chime,
           { schedule_id: schedule_id }
         )
       end

data/lib/inttegro/resources/spec.rb

@@ -3,13 +3,20 @@
 
 module Inttegro
   module Resources
+    # Read-only client for public country and financial-institution specifications.
+    #
+    # Access this resource through {Inttegro::Client#spec}.
     class Spec
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
 
+      # Retrieve supported countries, currencies, payment methods, banks, and providers.
+      #
+      # @return [Inttegro::Shared::CountrySpecifications] country specifications
       def countries
-        @http.post_model("/spec/countries", Inttegro::CountrySpecifications, {})
+        @http.post_model("/spec/countries", Inttegro::Shared::CountrySpecifications, {})
       end
     end
   end

data/lib/inttegro/resources/upload_requests.rb

@@ -3,11 +3,21 @@
 
 module Inttegro
   module Resources
+    # Client for delegated, policy-constrained file uploads.
+    #
+    # Access this resource through {Inttegro::Client#upload_requests}. Management methods use the
+    # client's API key; {#fulfill} uses the public capability URL and is intentionally unauthenticated.
     class UploadRequests
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
 
+      # Create a delegated upload request.
+      #
+      # @param payload [Hash, Inttegro::UploadRequest::CreateRequest] purpose, constraints, and expiry fields
+      # @param idempotency_key [String, nil] explicit key for safely retrying this logical write
+      # @return [Inttegro::UploadRequest] created upload request
       def create(payload, idempotency_key: nil)
         @http.post_resource(
           "/upload_requests/create",
@@ -17,18 +27,31 @@ module Inttegro
         )
       end
 
+      # Retrieve an upload request and its current attempt details.
+      #
+      # @param id [String] unique upload request identifier
+      # @return [Inttegro::UploadRequest::Details] upload request with attempt state
       def lookup(id:)
         @http.post_resource(
           "/upload_requests/lookup",
-          Inttegro::UploadRequestDetails, :upload_request,
+          Inttegro::UploadRequest::Details, :upload_request,
           { id: id }
         )
       end
 
+      # Retrieve a page of upload requests.
+      #
+      # @param payload [Hash, Inttegro::UploadRequest::PageRequest] pagination and filter fields
+      # @return [Inttegro::UploadRequest::Page] typed page of upload requests
       def page(payload = {})
-        @http.post_resource("/upload_requests/page", Inttegro::UploadRequestPage, :page, payload || {})
+        @http.post_resource("/upload_requests/page", Inttegro::UploadRequest::Page, :page, payload || {})
       end
 
+      # Cancel an active delegated upload request.
+      #
+      # @param payload [Hash, Inttegro::UploadRequest::CancelRequest] upload request identifier and metadata
+      # @param idempotency_key [String, nil] explicit key for safely retrying this logical write
+      # @return [Inttegro::UploadRequest] canceled upload request
       def cancel(payload, idempotency_key: nil)
         @http.post_resource(
           "/upload_requests/cancel",
@@ -38,19 +61,29 @@ module Inttegro
         )
       end
 
+      # Record a manual approval or rejection for a submitted upload attempt.
+      #
+      # @param payload [Hash, Inttegro::UploadRequest::ReviewAttemptRequest] attempt selector and review decision
+      # @param idempotency_key [String, nil] explicit key for safely retrying this logical write
+      # @return [Inttegro::UploadRequest::Details] updated request with review state
       def review(payload, idempotency_key: nil)
         @http.post_resource(
           "/upload_requests/review",
-          Inttegro::UploadRequestDetails, :upload_request,
+          Inttegro::UploadRequest::Details, :upload_request,
           payload,
           headers: headers(idempotency_key)
         )
       end
 
+      # Submit a file through the public delegated-upload capability URL.
+      #
+      # @param upload_url [String] complete capability URL returned when the upload request was created
+      # @param file [String] local path of the file to upload
+      # @return [Inttegro::Shared::UploadFulfillment] validation and fulfillment result
       def fulfill(upload_url:, file:)
         @http.post_multipart_model(
           upload_url,
-          Inttegro::UploadFulfillment,
+          Inttegro::Shared::UploadFulfillment,
           files: { file: file },
           authenticated: false,
           operation: "upload_requests.upload"

data/lib/inttegro/schedule/base.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+# typed: strict
+
+# Generated from openapi/commerce.yml by bin/generate-openapi-types. Do not edit.
+
+require "sorbet-runtime"
+
+module Inttegro
+  # Namespace for generated schedule models and enums.
+  #
+  # Each public type in this namespace is defined in its own file and follows the field names
+  # and wire values declared by the Inttegro OpenAPI contract.
+  #
+  # @api public
+  module Schedule
+  end
+end