inttegro 4.3.1 → 6.0.0

data/lib/inttegro/refund/refund.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+# typed: strict
+
+# Generated from openapi/commerce.yml by bin/generate-openapi-types. Do not edit.
+
+require_relative "base"
+require_relative "../money/amount"
+require_relative "line_item"
+require_relative "reason"
+require_relative "status"
+
+module Inttegro
+  # Typed representation of the refund object in the Inttegro API.
+  #
+  # This generated model is immutable. Construct it with `.new`, or decode a string-keyed API
+  # payload with `.from_hash`. `#serialize` produces a string-keyed hash using the original wire
+  # field names and serialized enum values.
+  #
+  # @api public
+  #
+  # @!attribute [r] canceled_at
+  #   Omitted unless the refund was canceled before processing began.
+  #
+  #   Optional in the API payload; omitted values default to `nil`. Wire name: `canceled_at`.
+  #   @return [Time, nil]
+  #
+  # @!attribute [r] created_at
+  #   Value of the `created_at` field in the Inttegro API payload.
+  #
+  #   Required in the API payload. Wire name: `created_at`.
+  #   @return [Time]
+  #
+  # @!attribute [r] custom_data
+  #   Merchant-defined string values attached to a resource. SDKs expose this as a semantic
+  #   collection rather than a raw map.
+  #
+  #   Optional in the API payload; omitted values default to `nil`. Wire name: `custom_data`.
+  #   @return [Hash{String => String}, nil]
+  #
+  # @!attribute [r] failed_at
+  #   Omitted unless processing failed.
+  #
+  #   Optional in the API payload; omitted values default to `nil`. Wire name: `failed_at`.
+  #   @return [Time, nil]
+  #
+  # @!attribute [r] id
+  #   Value of the `id` field in the Inttegro API payload.
+  #
+  #   Required in the API payload. Wire name: `id`.
+  #   @return [String]
+  #
+  # @!attribute [r] line_items
+  #   One or more immutable line-level refund allocations.
+  #
+  #   Required in the API payload. Wire name: `line_items`.
+  #   @return [Array<Inttegro::Refund::LineItem>]
+  #
+  # @!attribute [r] order_id
+  #   Value of the `order_id` field in the Inttegro API payload.
+  #
+  #   Required in the API payload. Wire name: `order_id`.
+  #   @return [String]
+  #
+  # @!attribute [r] processing_at
+  #   Omitted until processing starts.
+  #
+  #   Optional in the API payload; omitted values default to `nil`. Wire name: `processing_at`.
+  #   @return [Time, nil]
+  #
+  # @!attribute [r] reason
+  #   Value of the `reason` field in the Inttegro API payload.
+  #
+  #   Required in the API payload. Wire name: `reason`.
+  #   @return [Inttegro::Refund::Reason]
+  #
+  # @!attribute [r] reason_details
+  #   Value of the `reason_details` field in the Inttegro API payload.
+  #
+  #   Optional in the API payload; omitted values default to `nil`. Wire name: `reason_details`.
+  #   @return [String, nil]
+  #
+  # @!attribute [r] reference
+  #   Value of the `reference` field in the Inttegro API payload.
+  #
+  #   Optional in the API payload; omitted values default to `nil`. Wire name: `reference`.
+  #   @return [String, nil]
+  #
+  # @!attribute [r] status
+  #   Value of the `status` field in the Inttegro API payload.
+  #
+  #   Required in the API payload. Wire name: `status`.
+  #   @return [Inttegro::Refund::Status]
+  #
+  # @!attribute [r] succeeded_at
+  #   Omitted unless processing succeeded.
+  #
+  #   Optional in the API payload; omitted values default to `nil`. Wire name: `succeeded_at`.
+  #   @return [Time, nil]
+  #
+  # @!attribute [r] total
+  #   Value of the `total` field in the Inttegro API payload.
+  #
+  #   Required in the API payload. Wire name: `total`.
+  #   @return [Inttegro::Money::Amount]
+  class Refund
+    const :canceled_at, T.nilable(Time), default: nil
+    const :created_at, Time
+    const :custom_data, T.nilable(T::Hash[String, String]), default: nil
+    const :failed_at, T.nilable(Time), default: nil
+    const :id, String
+    const :line_items, T::Array[Inttegro::Refund::LineItem]
+    const :order_id, String
+    const :processing_at, T.nilable(Time), default: nil
+    const :reason, Inttegro::Refund::Reason
+    const :reason_details, T.nilable(String), default: nil
+    const :reference, T.nilable(String), default: nil
+    const :status, Inttegro::Refund::Status
+    const :succeeded_at, T.nilable(Time), default: nil
+    const :total, Inttegro::Money::Amount
+  end
+end

data/lib/inttegro/refund/request_meta.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# typed: strict
+
+# Generated from openapi/commerce.yml by bin/generate-openapi-types. Do not edit.
+
+require_relative "base"
+
+module Inttegro
+  class Refund
+    # Typed representation of the request meta object in the Inttegro API.
+    #
+    # This generated model is immutable. Construct it with `.new`, or decode a string-keyed API
+    # payload with `.from_hash`. `#serialize` produces a string-keyed hash using the original wire
+    # field names and serialized enum values.
+    #
+    # @api public
+    #
+    # @!attribute [r] idempotency_key
+    #   Body-level compatibility key. Prefer the `Idempotency-Key` header for new integrations.
+    #
+    #   Optional in the API payload; omitted values default to `nil`. Wire name: `idempotency_key`.
+    #   @return [String, nil]
+    class RequestMeta < T::Struct
+      const :idempotency_key, T.nilable(String), default: nil
+    end
+  end
+end

data/lib/inttegro/refund/response.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+# typed: strict
+
+# Generated from openapi/commerce.yml by bin/generate-openapi-types. Do not edit.
+
+require_relative "base"
+require_relative "refund"
+
+module Inttegro
+  class Refund
+    # Typed representation of the response object in the Inttegro API.
+    #
+    # This generated model is immutable. Construct it with `.new`, or decode a string-keyed API
+    # payload with `.from_hash`. `#serialize` produces a string-keyed hash using the original wire
+    # field names and serialized enum values.
+    #
+    # @api public
+    #
+    # @!attribute [r] refund
+    #   Value of the `refund` field in the Inttegro API payload.
+    #
+    #   Required in the API payload. Wire name: `refund`.
+    #   @return [Inttegro::Refund]
+    class Response < T::Struct
+      const :refund, Inttegro::Refund
+    end
+  end
+end

data/lib/inttegro/refund/status.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+# typed: strict
+
+# Generated from openapi/commerce.yml by bin/generate-openapi-types. Do not edit.
+
+require_relative "base"
+
+module Inttegro
+  class Refund
+    # String-backed values accepted by the Inttegro API for Inttegro::Refund::Status.
+    #
+    # Use the constants below when constructing a request. `#serialize` returns the documented
+    # string wire value received from or sent to the API.
+    #
+    # @api public
+    class Status < T::Enum
+      enums do
+        # Serialized wire value: `canceled`.
+        # @return [Inttegro::Refund::Status]
+        CANCELED = new("canceled")
+        # Serialized wire value: `failed`.
+        # @return [Inttegro::Refund::Status]
+        FAILED = new("failed")
+        # Serialized wire value: `pending`.
+        # @return [Inttegro::Refund::Status]
+        PENDING = new("pending")
+        # Serialized wire value: `processing`.
+        # @return [Inttegro::Refund::Status]
+        PROCESSING = new("processing")
+        # Serialized wire value: `succeeded`.
+        # @return [Inttegro::Refund::Status]
+        SUCCEEDED = new("succeeded")
+      end
+    end
+  end
+end

data/lib/inttegro/resources/apps.rb

@@ -2,20 +2,39 @@
 # typed: strict
 
 module Inttegro
+  # Resource clients exposed by {Inttegro::Client}.
+  #
+  # Each client owns one related set of API operations and converts successful responses into the
+  # resource-scoped models documented under {Inttegro}.
   module Resources
+    # Client for creating, reading, and updating Inttegro applications.
+    #
+    # Access this resource through {Inttegro::Client#apps}.
     class Apps
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
 
+      # Create an application and return its typed application record.
+      #
+      # @param payload [Hash, Inttegro::Application::CreateRequest] application creation fields
+      # @return [Inttegro::Application] created application
       def create(payload)
         @http.post_resource("/apps/create", Inttegro::Application, :app, payload)
       end
 
+      # Retrieve the application authenticated by the client's API key.
+      #
+      # @return [Inttegro::Application] authenticated application
       def lookup
         @http.post_resource("/apps/lookup", Inttegro::Application, :app, {})
       end
 
+      # Update mutable fields on the authenticated application.
+      #
+      # @param payload [Hash, Inttegro::Application::UpdateRequest] fields to change
+      # @return [Inttegro::Application] updated application
       def update(payload)
         @http.post_resource("/apps/update", Inttegro::Application, :app, payload)
       end

data/lib/inttegro/resources/balance_transactions.rb

@@ -3,19 +3,31 @@
 
 module Inttegro
   module Resources
+    # Read-only client for balance transactions recorded for the authenticated application.
+    #
+    # Access this resource through {Inttegro::Client#balance_transactions}.
     class BalanceTransactions
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
 
+      # Retrieve one balance transaction by its identifier.
+      #
+      # @param transaction_id [String] unique balance transaction identifier
+      # @return [Inttegro::BalanceTransaction] matching transaction
       def lookup(transaction_id:)
         @http.post_resource("/balance_transactions/lookup", Inttegro::BalanceTransaction, :transaction,
           { transaction_id: transaction_id }
         )
       end
 
+      # Retrieve a page of balance transactions.
+      #
+      # @param payload [Hash, Inttegro::BalanceTransaction::PageRequest] pagination and filter fields
+      # @return [Inttegro::BalanceTransaction::Page] typed page of transactions
       def page(payload = {})
-        @http.post_resource("/balance_transactions/page", Inttegro::BalanceTransactionPage, :page,
+        @http.post_resource("/balance_transactions/page", Inttegro::BalanceTransaction::Page, :page,
           payload || {}
         )
       end

data/lib/inttegro/resources/balances.rb

@@ -3,13 +3,20 @@
 
 module Inttegro
   module Resources
+    # Read-only client for the authenticated application's balance snapshot.
+    #
+    # Access this resource through {Inttegro::Client#balances}.
     class Balances
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
 
+      # Retrieve the latest strongly typed GHS balance snapshot.
+      #
+      # @return [Inttegro::Balance::Snapshot] available, pending, reserved, and refund balances
       def get
-        @http.post_model("/balances", Inttegro::BalanceSnapshot, {})
+        @http.post_resource("/balances", Inttegro::Balance::Snapshot, :balances, {})
       end
     end
   end

data/lib/inttegro/resources/broadcasts.rb

@@ -3,19 +3,31 @@
 
 module Inttegro
   module Resources
+    # Client for observing and canceling asynchronous Chime broadcasts.
+    #
+    # Access this resource through {Inttegro::Client#broadcasts}.
     class Broadcasts
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
 
+      # Retrieve a broadcast and its current delivery state.
+      #
+      # @param broadcast_id [String] unique broadcast identifier
+      # @return [Inttegro::Broadcast::Detail] broadcast details
       def lookup(broadcast_id:)
-        @http.post_resource("/broadcasts/lookup", Inttegro::BroadcastDetail, :broadcast,
+        @http.post_resource("/broadcasts/lookup", Inttegro::Broadcast::Detail, :broadcast,
           { broadcast_id: broadcast_id }
         )
       end
 
+      # Request cancellation of a broadcast that has not won its execution race.
+      #
+      # @param broadcast_id [String] unique broadcast identifier
+      # @return [Inttegro::Broadcast::CancelDetail] resulting cancellation details
       def cancel(broadcast_id:)
-        @http.post_resource("/broadcasts/cancel", Inttegro::BroadcastCancelDetail, :broadcast,
+        @http.post_resource("/broadcasts/cancel", Inttegro::Broadcast::CancelDetail, :broadcast,
           { broadcast_id: broadcast_id }
         )
       end

data/lib/inttegro/resources/chimes.rb

@@ -3,29 +3,53 @@
 
 module Inttegro
   module Resources
+    # Client for immediate, scheduled, and broadcast SMS or email notifications.
+    #
+    # Access this resource through {Inttegro::Client#chimes}.
     class Chimes
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
 
+      # Send one Chime immediately.
+      #
+      # @param payload [Hash, Inttegro::Chime::SendRequest] recipient and message data
+      # @return [Inttegro::Chime] created Chime and transmission state
       def send(payload)
         @http.post_resource("/chimes/send", Inttegro::Chime, :chime, payload)
       end
 
+      # Retrieve a sent Chime.
+      #
+      # @param chime_id [String] unique Chime identifier
+      # @return [Inttegro::Chime] matching Chime
       def lookup(chime_id:)
         @http.post_resource("/chimes/lookup", Inttegro::Chime, :chime, { chime_id: chime_id })
       end
 
+      # Retrieve a filtered page of Chimes.
+      #
+      # @param payload [Hash, Inttegro::Chime::PageRequest] pagination and filter fields
+      # @return [Inttegro::Chime::Page] typed page of Chimes
       def page(payload = {})
-        @http.post_resource("/chimes/page", Inttegro::ChimePage, :page, payload || {})
+        @http.post_resource("/chimes/page", Inttegro::Chime::Page, :page, payload || {})
       end
 
+      # Schedule one or more Chimes for future delivery.
+      #
+      # @param payload [Hash, Inttegro::Schedule::ChimeRequest] schedule and message data
+      # @return [Inttegro::Schedule::CreationDetail] created schedule
       def schedule(payload)
-        @http.post_resource("/chimes/schedule", Inttegro::ScheduleCreationDetail, :scheduled_chime, payload)
+        @http.post_resource("/chimes/schedule", Inttegro::Schedule::CreationDetail, :scheduled_chime, payload)
       end
 
+      # Start an asynchronous Chime broadcast.
+      #
+      # @param payload [Hash, Inttegro::Broadcast::Request] recipients and message data
+      # @return [Inttegro::Broadcast::CreationDetail] created broadcast
       def broadcast(payload)
-        @http.post_resource("/chimes/broadcast", Inttegro::BroadcastCreationDetail, :broadcast, payload)
+        @http.post_resource("/chimes/broadcast", Inttegro::Broadcast::CreationDetail, :broadcast, payload)
       end
     end
   end

data/lib/inttegro/resources/customers.rb

@@ -3,25 +3,45 @@
 
 module Inttegro
   module Resources
+    # Client for reusable customer profiles.
+    #
+    # Access this resource through {Inttegro::Client#customers}.
     class Customers
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
 
+      # Create a customer profile.
+      #
+      # @param payload [Hash, Inttegro::Customer::CreateRequest] customer fields
+      # @return [Inttegro::Customer] created customer
       def create(payload)
         @http.post_resource("/customers/create", Inttegro::Customer, :customer, payload)
       end
 
+      # Update supplied fields on an existing customer profile.
+      #
+      # @param payload [Hash, Inttegro::Customer::UpdateRequest] customer identifier and fields to change
+      # @return [Inttegro::Customer] updated customer
       def update(payload)
         @http.post_resource("/customers/update", Inttegro::Customer, :customer, payload)
       end
 
+      # Retrieve one customer by identifier.
+      #
+      # @param customer_id [String] unique customer identifier
+      # @return [Inttegro::Customer] matching customer
       def lookup(customer_id:)
         @http.post_resource("/customers/lookup", Inttegro::Customer, :customer, { customer_id: customer_id })
       end
 
+      # Retrieve a page of customers.
+      #
+      # @param payload [Hash, Inttegro::Customer::PageRequest] pagination fields
+      # @return [Inttegro::Customer::Page] typed page of customers
       def page(payload = {})
-        @http.post_resource("/customers/page", Inttegro::CustomerPage, :page, payload || {})
+        @http.post_resource("/customers/page", Inttegro::Customer::Page, :page, payload || {})
       end
     end
   end

data/lib/inttegro/resources/file_links.rb

@@ -3,28 +3,50 @@
 
 module Inttegro
   module Resources
+    # Client for revocable public capability URLs that deliver Inttegro files.
+    #
+    # Access this resource through {Inttegro::Client#file_links}.
     class FileLinks
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
 
+      # Create a public file link.
+      #
+      # @param payload [Hash, Inttegro::FileLink::CreateRequest] file, delivery, and expiry fields
+      # @param idempotency_key [String, nil] explicit key for safely retrying this logical write
+      # @return [Inttegro::FileLink::Creation] link metadata including the capability URL
       def create(payload, idempotency_key: nil)
         @http.post_model(
           "/file_links/create",
-          Inttegro::FileLinkCreation,
+          Inttegro::FileLink::Creation,
           payload,
           headers: headers(idempotency_key)
         )
       end
 
+      # Retrieve a file link without exposing its token material.
+      #
+      # @param id [String] unique file-link identifier
+      # @return [Inttegro::FileLink] matching file link
       def lookup(id:)
         @http.post_resource("/file_links/lookup", Inttegro::FileLink, :file_link, { id: id })
       end
 
+      # Retrieve a filtered page of file links.
+      #
+      # @param payload [Hash, Inttegro::FileLink::PageRequest] pagination and filter fields
+      # @return [Inttegro::FileLink::Page] typed page of file links
       def page(payload = {})
-        @http.post_resource("/file_links/page", Inttegro::FileLinkPage, :page, payload || {})
+        @http.post_resource("/file_links/page", Inttegro::FileLink::Page, :page, payload || {})
       end
 
+      # Revoke a file link so its capability URL can no longer serve the file.
+      #
+      # @param payload [Hash, Inttegro::FileLink::RevokeRequest] file-link identifier and request metadata
+      # @param idempotency_key [String, nil] explicit key for safely retrying this logical write
+      # @return [Inttegro::FileLink] revoked file link
       def revoke(payload, idempotency_key: nil)
         @http.post_resource("/file_links/revoke", Inttegro::FileLink, :file_link,
           payload,
@@ -32,6 +54,14 @@ module Inttegro
         )
       end
 
+      # Download the bytes exposed by a public file-link URL.
+      #
+      # This public capability request does not use the client's API key. When +save_to+ is
+      # supplied, the response is also written to that path before being returned.
+      #
+      # @param url [String] complete public file-link capability URL
+      # @param save_to [String, nil] optional local path for the downloaded bytes
+      # @return [Inttegro::FileDownload] response bytes and headers
       def open(url, save_to: nil)
         download = @http.get_binary_public(url)
         download.save_to(save_to) if save_to

data/lib/inttegro/resources/file_references.rb

@@ -3,15 +3,23 @@
 
 module Inttegro
   module Resources
+    # Client for reconciling the files referenced by another Inttegro resource.
+    #
+    # Access this resource through {Inttegro::Client#file_references}.
     class FileReferences
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
 
+      # Replace the complete set of live file references for one resource.
+      #
+      # @param payload [Hash, Inttegro::FileReference::ReconcileRequest] resource and replacement references
+      # @return [Inttegro::FileReference::Reconciliation] reconciliation result
       def reconcile(payload)
         @http.post_model(
           "/file_references/reconcile",
-          Inttegro::FileReferenceReconciliation,
+          Inttegro::FileReference::Reconciliation,
           payload
         )
       end

data/lib/inttegro/resources/files.rb

@@ -3,11 +3,23 @@
 
 module Inttegro
   module Resources
+    # Client for uploading, listing, downloading, and deleting application-owned files.
+    #
+    # Access this resource through {Inttegro::Client#files}.
     class Files
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
 
+      # Upload a file using multipart form data.
+      #
+      # @param file [String] local path of the file to upload
+      # @param purpose [String] API purpose assigned to the file
+      # @param title [String, nil] optional display title
+      # @param custom_data [Hash, nil] optional merchant-defined data
+      # @param idempotency_key [String, nil] explicit key for safely retrying this logical write
+      # @return [Inttegro::File] created file record
       def create(file:, purpose:, title: nil, custom_data: nil, idempotency_key: nil)
         headers = idempotency_key ? { "Idempotency-Key" => idempotency_key } : {}
         @http.post_multipart_resource("/files/create", Inttegro::File, :file,
@@ -17,18 +29,35 @@ module Inttegro
         )
       end
 
+      # Retrieve metadata for one file.
+      #
+      # @param file_id [String] unique file identifier
+      # @return [Inttegro::File] matching file record
       def lookup(file_id:)
         @http.post_resource("/files/lookup", Inttegro::File, :file, { file_id: file_id })
       end
 
+      # Retrieve a filtered page of files.
+      #
+      # @param payload [Hash, Inttegro::File::PageRequest] pagination and filter fields
+      # @return [Inttegro::File::Page] typed page of files
       def page(payload = {})
-        @http.post_resource("/files/page", Inttegro::FilePage, :page, payload || {})
+        @http.post_resource("/files/page", Inttegro::File::Page, :page, payload || {})
       end
 
+      # Retrieve the original bytes for a file.
+      #
+      # @param file_id [String] unique file identifier
+      # @param disposition [String] requested delivery disposition, normally +"attachment"+ or +"inline"+
+      # @return [Inttegro::FileDownload] response bytes and headers
       def contents(file_id:, disposition: "attachment")
         @http.post_binary_json("/files/contents", { file_id: file_id, disposition: disposition })
       end
 
+      # Tombstone a file and request backing-object cleanup under the API's reference policy.
+      #
+      # @param file_id [String] unique file identifier
+      # @return [Inttegro::File] deleted file record
       def delete(file_id:)
         @http.post_resource("/files/delete", Inttegro::File, :file, { file_id: file_id })
       end