growsurf-ruby 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 493b71b685dcab98c1c2633ab0c32d9339609bba972dafb665607039a0079142
-  data.tar.gz: 75af6a27ec19b8f9e1cc8cdf8b412c4c70f9405276f444f69b305c901ca51893
+  metadata.gz: a41d14943b58b41cb4cd260b998778f9c559a6bdd7b254f2f6ebf93cd750a3b2
+  data.tar.gz: 27480177fc199dc35742ec1502b410beba65c52447e1a93bf8b31023bd54bca7
 SHA512:
-  metadata.gz: 50054ac45d5711ca710ae6f4c16d24d4c10954fc7c0f17e99f279531e318c86663ffd866cbf263380ccc8697a902ffd3c7d78389f11a31ec74ac4c046e09fbf2
-  data.tar.gz: 6de111fb82f96ea5dbdd3c43c5c98f039f3a250c71ebd193a9ae3244f3896df02eb3bd82a6f0143ed947bee2456a8cc1f7f08da8ef48b69da0860904730e0966
+  metadata.gz: 13275a91aaf8cd2be079cbaf5152be1e8d61ec92319182f205f318b83a50bc7fe19eda3e868fb9d5fce3e797a3c862a7f2194a5f9c82a00f506577fa0d7d0114
+  data.tar.gz: 8a6e28b01ea9a4bcb4c5f01521e703b18e82e07fa21c87789bef83dcdf48ff318bc74617098965564f5f4c890a51d9e32d4b87214109007e1fdbb03fea60fc0a

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [1.5.0](https://github.com/growsurf/growsurf-ruby/compare/v1.4.0...v1.5.0) (2026-09-10)
+
+
+### Features
+
+* **api:** add campaign integrations list endpoint ([8d9ca3f](https://github.com/growsurf/growsurf-ruby/commit/8d9ca3f29169cd4ff79625eeba3c19035f2aaa66))
+* **api:** add EMBEDDABLE_ELEMENT portal view source ([0978220](https://github.com/growsurf/growsurf-ruby/commit/0978220cf482049b18bb7e615a3536e362966d6d))
+* **api:** add paymentProvider and testMode to transaction params ([f11947c](https://github.com/growsurf/growsurf-ruby/commit/f11947c1485f25f88aef6de555f894243767e3a8))
+* **api:** add refundHistoryComplete to refund transaction params ([3d765f7](https://github.com/growsurf/growsurf-ruby/commit/3d765f73aad7faf38c798d36dc3355689460fda0))
+* **api:** expose response headers and sync reward and analytics models ([8f0859e](https://github.com/growsurf/growsurf-ruby/commit/8f0859e8b09fe3cf0098b4805f513bbd39c3a76b))
+* **api:** sync analytics and program resources ([1cc5cd2](https://github.com/growsurf/growsurf-ruby/commit/1cc5cd2eca64cfa792ded6bd84c198a348eb9f00))
+
+
+### Bug Fixes
+
+* accept explicit nil in setters for nullable and optional fields ([5d5dc21](https://github.com/growsurf/growsurf-ruby/commit/5d5dc216ee160ea5fbbab8bacfa8731238937e67))
+
+
+### Documentation
+
+* clarify participant email addresses must be unencoded ([b22d681](https://github.com/growsurf/growsurf-ruby/commit/b22d681f111b31cd29fbd530912f05ef2c04b3b2))
+
+## [1.4.0](https://github.com/growsurf/growsurf-ruby/compare/v1.3.0...v1.4.0) (2026-08-25)
+
+
+### Features
+
+* **api:** add reward and commission event support ([a9d672f](https://github.com/growsurf/growsurf-ruby/commit/a9d672ff9fd34198b8919adbf207436a023841b4))
+
 ## [1.3.0](https://github.com/growsurf/growsurf-ruby/compare/v1.2.1...v1.3.0) (2026-08-23)
 
 

data/README.md

@@ -2,13 +2,13 @@
 
 The Growsurf Ruby library provides convenient access to the Growsurf REST API from any Ruby 3.2.0+ application. It ships with comprehensive types & docstrings in Yard, RBS, and RBI – [see below](https://github.com/growsurf/growsurf-ruby#Sorbet) for usage with Sorbet. The standard library's `net/http` is used as the HTTP transport, with connection pooling via the `connection_pool` gem.
 
-It is generated with [Stainless](https://www.stainless.com/).
+This library was originally generated with [Stainless](https://www.stainless.com/) and is now maintained by GrowSurf.
 
 ## Documentation
 
 Documentation for releases of this gem can be found [on RubyDoc](https://gemdocs.org/gems/growsurf-ruby).
 
-The REST API documentation can be found on [growsurf.com](https://growsurf.com/settings#contact_support).
+See the [GrowSurf REST API reference](https://docs.growsurf.com/developer-tools/rest-api/api-reference) for endpoint documentation.
 
 ## Installation
 
@@ -17,7 +17,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "growsurf-ruby", "~> 1.3.0"
+gem "growsurf-ruby", "~> 1.5.0"
 ```
 
 <!-- x-release-please-end -->
@@ -73,9 +73,9 @@ Error codes are as follows:
 
 ### Retries
 
-Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
+Retryable requests are automatically retried 2 times by default, with a short exponential backoff.
 
-Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.
+Automatic retries apply only to `GET` and `HEAD` requests, plus `POST /api-key/rotate`. For those requests, the library retries connection errors, timeouts, HTTP 408, HTTP 409, HTTP 429, and HTTP 5xx responses. Other mutations are never retried automatically.
 
 You can use the `max_retries` option to configure or disable this:
 
@@ -105,7 +105,7 @@ growsurf.campaign.list(request_options: {timeout: 5})
 
 On timeout, `GrowsurfRuby::Errors::APITimeoutError` is raised.
 
-Note that requests that time out are retried by default.
+A timed-out request is retried only when it meets the retry rules above.
 
 ## Advanced concepts
 
@@ -121,6 +121,9 @@ All parameter and response objects inherit from `GrowsurfRuby::Internal::Type::B
 
 4. Helpers such as `#to_h`, `#deep_to_h`, `#to_json`, and `#to_yaml`.
 
+5. Normalized HTTP response headers through `#response_headers`. For example,
+   `response.response_headers["ratelimit"]` exposes the current rate-limit state.
+
 ### Making custom or undocumented requests
 
 #### Undocumented properties
@@ -221,7 +224,7 @@ growsurf.campaign.create_mobile_participant_token(
 
 ## Versioning
 
-This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time.
+This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. Breaking API changes use a new major version.
 
 This package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` type definitions to be non-breaking changes.
 

data/lib/growsurf_ruby/internal/transport/base_client.rb

@@ -532,7 +532,12 @@ module GrowsurfRuby
             page.new(client: self, req: req, headers: headers, page_data: decoded)
           else
             unwrapped = GrowsurfRuby::Internal::Util.dig(decoded, unwrap)
-            GrowsurfRuby::Internal::Type::Converter.coerce(model, unwrapped)
+            result = GrowsurfRuby::Internal::Type::Converter.coerce(model, unwrapped)
+            if result.is_a?(GrowsurfRuby::Internal::Type::BaseModel)
+              result.attach_response_headers(headers)
+            else
+              result
+            end
           end
         end
 

data/lib/growsurf_ruby/internal/type/base_model.rb

@@ -82,6 +82,14 @@ module GrowsurfRuby
             define_method(setter) do |value|
               target = type_fn.call
               state = GrowsurfRuby::Internal::Type::Converter.new_coerce_state(translate_names: false)
+              # Mirror `.coerce`: an explicit `nil` is valid for nullable and optional fields,
+              # so it must not be coerced against the field type and recorded as an error.
+              if value.nil? && (nilable || !required)
+                @coerced.store(name_sym, true)
+                @data.store(name_sym, nil)
+                next
+              end
+
               coerced = GrowsurfRuby::Internal::Type::Converter.coerce(target, value, state: state)
               status = @coerced.store(name_sym, state.fetch(:error) || true)
               stored =
@@ -433,6 +441,23 @@ module GrowsurfRuby
         # @return [Hash{Symbol=>Object}]
         def deep_to_h = self.class.recursively_to_h(@data, convert: false)
 
+        # @api public
+        #
+        # Returns the normalized HTTP response headers for models returned by the client.
+        # Models created directly have no response headers.
+        #
+        # @return [Hash{String=>String}]
+        attr_reader :response_headers
+
+        # @api private
+        #
+        # @param headers [Hash{String=>String}]
+        # @return [self]
+        def attach_response_headers(headers)
+          @response_headers = headers.freeze
+          self
+        end
+
         # @param keys [Array<Symbol>, nil]
         #
         # @return [Hash{Symbol=>Object}]
@@ -476,6 +501,7 @@ module GrowsurfRuby
         def initialize(data = {})
           @data = {}
           @coerced = {}
+          @response_headers = {}.freeze
           GrowsurfRuby::Internal::Util.coerce_hash!(data).each do
             if self.class.known_fields.key?(_1)
               public_send(:"#{_1}=", _2)

data/lib/growsurf_ruby/internal/type/base_page.rb

@@ -35,6 +35,11 @@ module GrowsurfRuby
 
         alias_method :enum_for, :to_enum
 
+        # @api public
+        #
+        # @return [Hash{String=>String}]
+        attr_reader :response_headers
+
         # @api private
         #
         # @param client [GrowsurfRuby::Internal::Transport::BaseClient]
@@ -45,6 +50,7 @@ module GrowsurfRuby
           @client = client
           @req = req
           @model = req.fetch(:model)
+          @response_headers = headers.freeze
           super()
         end
 

data/lib/growsurf_ruby/models/account_create_response.rb

@@ -5,9 +5,9 @@ module GrowsurfRuby
     # @see GrowsurfRuby::Resources::Account#create
     class AccountCreateResponse < GrowsurfRuby::Internal::Type::BaseModel
       # @!attribute api_key
-      #   An API key for the new account. Use it as the `Bearer` token on subsequent
-      #   requests. Locked (`403` `EMAIL_NOT_VERIFIED_ERROR`) until the account's email
-      #   is verified, and rotated when the account owner first signs in to the GrowSurf
+      #   An API key for the new account. Use it as the `Bearer` token on subsequent requests. Locked (`403`
+      #   `EMAIL_NOT_VERIFIED_ERROR`) until the account's email is verified; verification unlocks this same
+      #   key, so keep it and retry. It is replaced only when the account owner first signs in to the GrowSurf
       #   dashboard.
       #
       #   @return [String]

data/lib/growsurf_ruby/models/analytics_availability.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module GrowsurfRuby
+  module Models
+    module AnalyticsAvailability
+      extend GrowsurfRuby::Internal::Type::Enum
+
+      AVAILABLE = :AVAILABLE
+      PARTIAL = :PARTIAL
+      UNAVAILABLE = :UNAVAILABLE
+
+      # @!method self.values
+      #   @return [Array<Symbol>]
+    end
+  end
+end

data/lib/growsurf_ruby/models/analytics_unavailable_reason.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module GrowsurfRuby
+  module Models
+    module AnalyticsUnavailableReason
+      extend GrowsurfRuby::Internal::Type::Enum
+
+      COVERAGE_UNAVAILABLE = :COVERAGE_UNAVAILABLE
+      PRE_COVERAGE = :PRE_COVERAGE
+      PARTIAL_COVERAGE = :PARTIAL_COVERAGE
+      INSUFFICIENT_COVERAGE = :INSUFFICIENT_COVERAGE
+      EMPTY_DENOMINATOR = :EMPTY_DENOMINATOR
+      QUERY_LIMIT_EXCEEDED = :QUERY_LIMIT_EXCEEDED
+      PARTICIPANT_NOT_ELIGIBLE = :PARTICIPANT_NOT_ELIGIBLE
+
+      # @!method self.values
+      #   @return [Array<Symbol>]
+    end
+  end
+end

data/lib/growsurf_ruby/models/campaign/delete_program_resource_response.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module GrowsurfRuby
+  module Models
+    module Campaign
+      class DeleteProgramResourceResponse < GrowsurfRuby::Internal::Type::BaseModel
+        required :id, String
+        required :success, GrowsurfRuby::Internal::Type::Boolean
+      end
+    end
+  end
+end

data/lib/growsurf_ruby/models/campaign/integration.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module GrowsurfRuby
+  module Models
+    module Campaign
+      # @see GrowsurfRuby::Resources::Campaign::Integrations#list
+      class Integration < GrowsurfRuby::Internal::Type::BaseModel
+        # @!attribute id
+        #   Stable integration key, the same value the GrowSurf dashboard uses for this
+        #   integration.
+        #
+        #   @return [String]
+        required :id, String
+
+        # @!attribute auto_disabled
+        #   Whether GrowSurf switched the integration off after repeated delivery failures.
+        #   Its credentials are still stored, but it delivers nothing until it is
+        #   reconnected in the GrowSurf dashboard.
+        #
+        #   @return [Boolean]
+        required :auto_disabled, GrowsurfRuby::Internal::Type::Boolean, api_name: :autoDisabled
+
+        # @!attribute connect_url
+        #   Dashboard link that opens this integration's connect panel in the GrowSurf Program
+        #   Editor. Give it to the person running the program: connecting an account is a step they
+        #   complete in the dashboard, and the API cannot do it for them.
+        #
+        #   @return [String]
+        required :connect_url, String, api_name: :connectUrl
+
+        # @!attribute connected
+        #   Whether the program has stored credentials for this integration.
+        #
+        #   @return [Boolean]
+        required :connected, GrowsurfRuby::Internal::Type::Boolean
+
+        # @!attribute enabled
+        #   Whether the integration is switched on and currently working.
+        #
+        #   @return [Boolean]
+        required :enabled, GrowsurfRuby::Internal::Type::Boolean
+
+        # @!attribute name
+        #   Display name, matching what the GrowSurf dashboard calls this integration.
+        #
+        #   @return [String]
+        required :name, String
+
+        # @!method initialize(id:, auto_disabled:, connect_url:, connected:, enabled:, name:)
+        #   Some parameter documentations has been truncated, see
+        #   {GrowsurfRuby::Models::Campaign::Integration} for more details.
+        #
+        #   One integration a program can connect, with its current state.
+        #
+        #   @param id [String] Stable integration key, the same value the GrowSurf dashboard uses for this integ
+        #
+        #   @param auto_disabled [Boolean] Whether GrowSurf switched the integration off after repeated delivery failures. I
+        #
+        #   @param connect_url [String] Dashboard link that opens this integration's connect panel in the GrowSurf Progra
+        #
+        #   @param connected [Boolean] Whether the program has stored credentials for this integration.
+        #
+        #   @param enabled [Boolean] Whether the integration is switched on and currently working.
+        #
+        #   @param name [String] Display name, matching what the GrowSurf dashboard calls this integration.
+      end
+    end
+  end
+end

data/lib/growsurf_ruby/models/campaign/integration_list_response.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module GrowsurfRuby
+  module Models
+    module Campaign
+      # @see GrowsurfRuby::Resources::Campaign::Integrations#list
+      class IntegrationListResponse < GrowsurfRuby::Internal::Type::BaseModel
+        # @!attribute integrations
+        #   Every integration this program can connect, in the order the GrowSurf dashboard
+        #   lists them.
+        #
+        #   @return [Array<GrowsurfRuby::Models::Campaign::Integration>]
+        required :integrations,
+                 -> { GrowsurfRuby::Internal::Type::ArrayOf[GrowsurfRuby::Campaign::Integration] }
+
+        # @!method initialize(integrations:)
+        #   Some parameter documentations has been truncated, see
+        #   {GrowsurfRuby::Models::Campaign::IntegrationListResponse} for more details.
+        #
+        #   @param integrations [Array<GrowsurfRuby::Models::Campaign::Integration>] Every integration this program can connect, in the order the GrowSurf dashboard l
+      end
+    end
+  end
+end

data/lib/growsurf_ruby/models/campaign/participant_activation_analytics.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module GrowsurfRuby
+  module Models
+    module Campaign
+      # Covered first milestones for one participant. Unknown history remains `nil` and
+      # is paired with an explicit state and reason.
+      class ParticipantActivationAnalytics < GrowsurfRuby::Internal::Type::BaseModel
+        required :coverage_start_at, Integer, api_name: :coverageStartAt, nil?: true
+        required :metric_contract_version, Integer, api_name: :metricContractVersion
+        required :program_type, enum: -> { ProgramType }, api_name: :programType
+        required :state, enum: -> { GrowsurfRuby::Models::AnalyticsAvailability }
+        required :reason, enum: -> { GrowsurfRuby::Models::AnalyticsUnavailableReason }, nil?: true
+        required :cohort, -> { Cohort }
+        required :enrolled_as_advocate_at, Integer, api_name: :enrolledAsAdvocateAt, nil?: true
+        required :milestones, -> { Milestones }
+
+        module ProgramType
+          extend GrowsurfRuby::Internal::Type::Enum
+
+          REFERRAL = :REFERRAL
+          AFFILIATE = :AFFILIATE
+        end
+
+        module AnchorField
+          extend GrowsurfRuby::Internal::Type::Enum
+
+          ENROLLED_AS_ADVOCATE_AT = :enrolledAsAdvocateAt
+          APPROVED_AS_AFFILIATE_AT = :approvedAsAffiliateAt
+        end
+
+        class Cohort < GrowsurfRuby::Internal::Type::BaseModel
+          required :anchor_field, enum: -> { AnchorField }, api_name: :anchorField
+          required :anchor_at, Integer, api_name: :anchorAt, nil?: true
+        end
+
+        module ShareChannel
+          extend GrowsurfRuby::Internal::Type::Enum
+
+          EMAIL = :email
+          FACEBOOK = :facebook
+          TWITTER = :twitter
+          LINKEDIN = :linkedin
+          PINTEREST = :pinterest
+          THREADS = :threads
+          BLUESKY = :bluesky
+          SMS = :sms
+          MESSENGER = :messenger
+          WHATSAPP = :whatsapp
+          WECHAT = :wechat
+          TELEGRAM = :telegram
+          REDDIT = :reddit
+          TUMBLR = :tumblr
+          QRCODE = :qrcode
+          COPY_REF_LINK = :copyRefLink
+          IOS_NATIVE_SHARE = :iosNativeShare
+          ANDROID_NATIVE_SHARE = :androidNativeShare
+        end
+
+        class Milestones < GrowsurfRuby::Internal::Type::BaseModel
+          required :first_portal_viewed_at, Integer, api_name: :firstPortalViewedAt, nil?: true
+          required :first_referral_link_copied_at, Integer, api_name: :firstReferralLinkCopiedAt, nil?: true
+          required :first_share_at, Integer, api_name: :firstShareAt, nil?: true
+          required :first_share_channel, enum: -> { ShareChannel }, api_name: :firstShareChannel, nil?: true
+          required :first_unique_click_at, Integer, api_name: :firstUniqueClickAt, nil?: true
+          required :first_lead_at, Integer, api_name: :firstLeadAt, nil?: true
+          required :first_referral_at, Integer, api_name: :firstReferralAt, nil?: true
+          required :first_reward_at, Integer, api_name: :firstRewardAt, nil?: true
+          required :first_commission_at, Integer, api_name: :firstCommissionAt, nil?: true
+          required :payout_setup_completed_at, Integer, api_name: :payoutSetupCompletedAt, nil?: true
+        end
+      end
+    end
+  end
+end

data/lib/growsurf_ruby/models/campaign/participant_analytics_response.rb

@@ -23,6 +23,9 @@ module GrowsurfRuby
                  GrowsurfRuby::Internal::Type::HashOf[Integer],
                  api_name: :shareCount
 
+        # Present only when `include` contains `activation`.
+        optional :activation, -> { GrowsurfRuby::Models::Campaign::ParticipantActivationAnalytics }
+
         # Present only when `include` contains `email`.
         optional :email, -> { GrowsurfRuby::Models::EmailAnalytics }
 
@@ -270,6 +273,10 @@ module GrowsurfRuby
           #   @return [Integer, nil]
           optional :pinterest_shares, Integer, api_name: :pinterestShares
 
+          # Covered portal views when both `activation` and `series` are requested.
+          # Unknown history is `nil`.
+          optional :portal_views, Integer, api_name: :portalViews, nil?: true
+
           # @!attribute qrcode_shares
           #
           #   @return [Integer, nil]
@@ -300,6 +307,10 @@ module GrowsurfRuby
           #   @return [Integer, nil]
           optional :sms_shares, Integer, api_name: :smsShares
 
+          # Covered share actions when both `activation` and `series` are requested.
+          # Unknown history is `nil`.
+          optional :share_actions, Integer, api_name: :shareActions, nil?: true
+
           # @!attribute telegram_shares
           #
           #   @return [Integer, nil]

data/lib/growsurf_ruby/models/campaign/participant_get_payout_destination_response.rb

@@ -10,14 +10,14 @@ module GrowsurfRuby
         #   one.
         #
         #   @return [String, nil]
-        optional :active_provider, String, api_name: :activeProvider, nil?: true
+        required :active_provider, String, api_name: :activeProvider, nil?: true
 
         # @!attribute destinations
         #   One entry per enabled payout provider describing the participant's destination
         #   for it.
         #
-        #   @return [Array<GrowsurfRuby::Models::Campaign::ParticipantGetPayoutDestinationResponse::Destination>, nil]
-        optional :destinations,
+        #   @return [Array<GrowsurfRuby::Models::Campaign::ParticipantGetPayoutDestinationResponse::Destination>]
+        required :destinations,
                  -> {
                    GrowsurfRuby::Internal::Type::ArrayOf[
                      GrowsurfRuby::Campaign::ParticipantGetPayoutDestinationResponse::Destination
@@ -27,14 +27,14 @@ module GrowsurfRuby
         # @!attribute enabled_providers
         #   The payout providers enabled for this program.
         #
-        #   @return [Array<String>, nil]
-        optional :enabled_providers,
+        #   @return [Array<String>]
+        required :enabled_providers,
                  -> {
                    GrowsurfRuby::Internal::Type::ArrayOf[String]
                  },
                  api_name: :enabledProviders
 
-        # @!method initialize(active_provider: nil, destinations: nil, enabled_providers: nil)
+        # @!method initialize(active_provider:, destinations:, enabled_providers:)
         #   @param active_provider [String, nil] The provider that currently gets paid, or null until the participant confirms one.
         #
         #   @param destinations [Array<GrowsurfRuby::Models::Campaign::ParticipantGetPayoutDestinationResponse::Destination>] One entry per enabled payout provider describing the participant's destination for it.
@@ -47,19 +47,19 @@ module GrowsurfRuby
           #   The confirmed payout email for this provider.
           #
           #   @return [String, nil]
-          optional :claim_email, String, api_name: :claimEmail, nil?: true
+          required :claim_email, String, api_name: :claimEmail, nil?: true
 
           # @!attribute confirmed_at
           #   When the destination was confirmed, as a Unix timestamp in milliseconds.
           #
           #   @return [Integer, nil]
-          optional :confirmed_at, Integer, api_name: :confirmedAt, nil?: true
+          required :confirmed_at, Integer, api_name: :confirmedAt, nil?: true
 
           # @!attribute legal_entity_type
           #   The legal recipient type the participant confirmed, if any.
           #
           #   @return [Symbol, GrowsurfRuby::Models::Campaign::ParticipantGetPayoutDestinationResponse::Destination::LegalEntityType, nil]
-          optional :legal_entity_type,
+          required :legal_entity_type,
                    enum: -> {
                      GrowsurfRuby::Campaign::ParticipantGetPayoutDestinationResponse::Destination::LegalEntityType
                    },
@@ -70,29 +70,29 @@ module GrowsurfRuby
           #   When status is `NEEDS_REPAIR`, why (e.g. a bounced delivery).
           #
           #   @return [String, nil]
-          optional :needs_repair_reason, String, api_name: :needsRepairReason, nil?: true
+          required :needs_repair_reason, String, api_name: :needsRepairReason, nil?: true
 
           # @!attribute provider
           #   The payout provider this entry describes.
           #
-          #   @return [String, nil]
-          optional :provider, String
+          #   @return [String]
+          required :provider, String
 
           # @!attribute provider_display_name
           #   The customer-facing provider name (e.g. "PayPal", "Wise").
           #
-          #   @return [String, nil]
-          optional :provider_display_name, String, api_name: :providerDisplayName
+          #   @return [String]
+          required :provider_display_name, String, api_name: :providerDisplayName
 
           # @!attribute status
           #   The destination's current status: `NONE` (not set up), `PENDING_CONFIRMATION`,
           #   `CONFIRMED`, `ACTIVE`, `NEEDS_REPAIR`, or `EXPIRED`. Historical superseded
           #   or revoked destinations are projected as `NONE`.
           #
-          #   @return [String, nil]
-          optional :status, String
+          #   @return [String]
+          required :status, String
 
-          # @!method initialize(claim_email: nil, confirmed_at: nil, legal_entity_type: nil, needs_repair_reason: nil, provider: nil, provider_display_name: nil, status: nil)
+          # @!method initialize(claim_email:, confirmed_at:, legal_entity_type:, needs_repair_reason:, provider:, provider_display_name:, status:)
           #   @param claim_email [String, nil] The confirmed payout email for this provider.
           #
           #   @param confirmed_at [Integer, nil] When the destination was confirmed, as a Unix timestamp in milliseconds.

data/lib/growsurf_ruby/models/campaign/participant_record_transaction_params.rb

@@ -137,7 +137,13 @@ module GrowsurfRuby
         #   @return [String, nil]
         optional :transaction_id, String, api_name: :transactionId
 
-        # @!method initialize(id:, participant_id_or_email:, currency:, gross_amount:, amount_cash_net: nil, amount_paid: nil, charge_id: nil, customer_id: nil, description: nil, external_id: nil, invoice_id: nil, invoice_subtotal_excluding_tax: nil, invoice_total: nil, invoice_total_excluding_tax: nil, net_amount: nil, order_id: nil, paid_at: nil, payment_id: nil, payment_intent_id: nil, subscription_id: nil, tax_amount: nil, total_tax_amount: nil, total_tax_amounts: nil, total_taxes: nil, transaction_id: nil, request_options: {})
+        # Connected provider: `stripe`, `chargebee` or `recurly`. Requires `transactionId` and `testMode`.
+        optional :payment_provider, String, api_name: :paymentProvider
+
+        # `true` for test or `false` for live. Requires `paymentProvider`.
+        optional :test_mode, GrowsurfRuby::Internal::Type::Boolean, api_name: :testMode
+
+        # @!method initialize(id:, participant_id_or_email:, currency:, gross_amount:, amount_cash_net: nil, amount_paid: nil, charge_id: nil, customer_id: nil, description: nil, external_id: nil, invoice_id: nil, invoice_subtotal_excluding_tax: nil, invoice_total: nil, invoice_total_excluding_tax: nil, net_amount: nil, order_id: nil, paid_at: nil, payment_id: nil, payment_intent_id: nil, subscription_id: nil, tax_amount: nil, total_tax_amount: nil, total_tax_amounts: nil, total_taxes: nil, transaction_id: nil, payment_provider: nil, test_mode: nil, request_options: {})
         #   @param id [String]
         #   @param participant_id_or_email [String]
         #   @param currency [String]
@@ -163,6 +169,8 @@ module GrowsurfRuby
         #   @param total_tax_amounts [Array<Hash{Symbol=>Object}>]
         #   @param total_taxes [Array<Hash{Symbol=>Object}>]
         #   @param transaction_id [String]
+        #   @param payment_provider [String]
+        #   @param test_mode [Boolean]
         #   @param request_options [GrowsurfRuby::RequestOptions, Hash{Symbol=>Object}]
       end
     end

data/lib/growsurf_ruby/models/campaign/participant_refund_transaction_params.rb

@@ -76,11 +76,18 @@ module GrowsurfRuby
         optional :payment_intent_id, String, api_name: :paymentIntentId
 
         # @!attribute refund_amount
+        #   Positive amount for this individual refund, no greater than the sale amount, in minor units. Record it with `refundId` on each original refund to support cancellation and out-of-order amendments. A cancellation may omit an already recorded amount. Missing or conflicting refund history returns `409` without applying the cancellation. Newly observed higher cumulative refunds and incomplete coverage are retained for reconciliation.
         #
         #   @return [Integer, nil]
         optional :refund_amount, Integer, api_name: :refundAmount
 
+        # Confirm only after every original refund ID and amount is recorded, including canceled refunds.
+        # Resolves previously incomplete history. Replaying an old confirmation cannot resolve a later gap; confirm a newly reconciled refund or complete provider list.
+        optional :refund_history_complete, GrowsurfRuby::Internal::Type::Boolean, api_name: :refundHistoryComplete
+
         # @!attribute refund_id
+        #   Stable per-refund identifier. Required when canceling a refund or changing the
+        #   refunded total after a cancellation. Reuse the original refund's identifier for its cancellation.
         #
         #   @return [String, nil]
         optional :refund_id, String, api_name: :refundId
@@ -95,7 +102,13 @@ module GrowsurfRuby
         #   @return [String, nil]
         optional :transaction_id, String, api_name: :transactionId
 
-        # @!method initialize(id:, participant_id_or_email:, amendment_type: nil, amount: nil, amount_refunded: nil, charge_id: nil, currency: nil, description: nil, external_id: nil, invoice_id: nil, order_id: nil, payment_id: nil, payment_intent_id: nil, refund_amount: nil, refund_id: nil, refund_status: nil, transaction_id: nil, request_options: {})
+        # Connected provider: `stripe`, `chargebee` or `recurly`. Requires `transactionId` and `testMode`.
+        optional :payment_provider, String, api_name: :paymentProvider
+
+        # `true` for test or `false` for live. Requires `paymentProvider`.
+        optional :test_mode, GrowsurfRuby::Internal::Type::Boolean, api_name: :testMode
+
+        # @!method initialize(id:, participant_id_or_email:, amendment_type: nil, amount: nil, amount_refunded: nil, charge_id: nil, currency: nil, description: nil, external_id: nil, invoice_id: nil, order_id: nil, payment_id: nil, payment_intent_id: nil, refund_amount: nil, refund_history_complete: nil, refund_id: nil, refund_status: nil, transaction_id: nil, payment_provider: nil, test_mode: nil, request_options: {})
         #   @param id [String]
         #   @param participant_id_or_email [String]
         #   @param amendment_type [Symbol, GrowsurfRuby::Models::Campaign::ParticipantRefundTransactionParams::AmendmentType]
@@ -110,9 +123,12 @@ module GrowsurfRuby
         #   @param payment_id [String]
         #   @param payment_intent_id [String]
         #   @param refund_amount [Integer]
+        #   @param refund_history_complete [Boolean]
         #   @param refund_id [String]
         #   @param refund_status [String]
         #   @param transaction_id [String]
+        #   @param payment_provider [String]
+        #   @param test_mode [Boolean]
         #   @param request_options [GrowsurfRuby::RequestOptions, Hash{Symbol=>Object}]
 
         module AmendmentType