growsurf-ruby 1.3.0 → 1.5.0

data/lib/growsurf_ruby/models/participant_commission_list.rb

@@ -46,6 +46,12 @@ module GrowsurfRuby
         #   @return [String]
         required :currency_iso, String, api_name: :currencyISO
 
+        # @!attribute event
+        #   The event that generated this commission. Legacy commissions return `SALE`.
+        #
+        #   @return [Symbol, GrowsurfRuby::Models::ParticipantCommissionList::Commission::Event]
+        required :event, enum: -> { GrowsurfRuby::ParticipantCommissionList::Commission::Event }
+
         # @!attribute referred_id
         #
         #   @return [String]
@@ -74,7 +80,7 @@ module GrowsurfRuby
         # @!attribute approved_at
         #
         #   @return [Integer, nil]
-        optional :approved_at, Integer, api_name: :approvedAt
+        optional :approved_at, Integer, api_name: :approvedAt, nil?: true
 
         # @!attribute campaign_currency_iso
         #
@@ -89,7 +95,7 @@ module GrowsurfRuby
         # @!attribute exchange_rate_at
         #
         #   @return [Integer, nil]
-        optional :exchange_rate_at, Integer, api_name: :exchangeRateAt
+        optional :exchange_rate_at, Integer, api_name: :exchangeRateAt, nil?: true
 
         # @!attribute fx_error
         #
@@ -104,12 +110,12 @@ module GrowsurfRuby
         # @!attribute paid_at
         #
         #   @return [Integer, nil]
-        optional :paid_at, Integer, api_name: :paidAt
+        optional :paid_at, Integer, api_name: :paidAt, nil?: true
 
         # @!attribute payout_queued_at
         #
         #   @return [Integer, nil]
-        optional :payout_queued_at, Integer, api_name: :payoutQueuedAt
+        optional :payout_queued_at, Integer, api_name: :payoutQueuedAt, nil?: true
 
         # @!attribute provider
         #
@@ -119,7 +125,7 @@ module GrowsurfRuby
         # @!attribute reversed_at
         #
         #   @return [Integer, nil]
-        optional :reversed_at, Integer, api_name: :reversedAt
+        optional :reversed_at, Integer, api_name: :reversedAt, nil?: true
 
         # @!attribute sale_amount_in_campaign_currency
         #
@@ -129,11 +135,12 @@ module GrowsurfRuby
                  api_name: :saleAmountInCampaignCurrency,
                  nil?: true
 
-        # @!method initialize(id:, amount:, created_at:, currency_iso:, referred_id:, referrer_id:, sale_amount:, status:, amount_in_campaign_currency: nil, approved_at: nil, campaign_currency_iso: nil, exchange_rate: nil, exchange_rate_at: nil, fx_error: nil, hold_duration: nil, paid_at: nil, payout_queued_at: nil, provider: nil, reversed_at: nil, sale_amount_in_campaign_currency: nil)
+        # @!method initialize(id:, amount:, created_at:, currency_iso:, event:, referred_id:, referrer_id:, sale_amount:, status:, amount_in_campaign_currency: nil, approved_at: nil, campaign_currency_iso: nil, exchange_rate: nil, exchange_rate_at: nil, fx_error: nil, hold_duration: nil, paid_at: nil, payout_queued_at: nil, provider: nil, reversed_at: nil, sale_amount_in_campaign_currency: nil)
         #   @param id [String]
         #   @param amount [Integer, nil]
         #   @param created_at [Integer]
         #   @param currency_iso [String]
+        #   @param event [Symbol, GrowsurfRuby::Models::ParticipantCommissionList::Commission::Event] The event that generated this commission. Legacy commissions return `SALE`.
         #   @param referred_id [String]
         #   @param referrer_id [String]
         #   @param sale_amount [Integer, nil]
@@ -151,6 +158,17 @@ module GrowsurfRuby
         #   @param reversed_at [Integer]
         #   @param sale_amount_in_campaign_currency [Integer, nil]
 
+        # @see GrowsurfRuby::Models::ParticipantCommissionList::Commission#event
+        module Event
+          extend GrowsurfRuby::Internal::Type::Enum
+
+          LEAD = :LEAD
+          SALE = :SALE
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+
         # @see GrowsurfRuby::Models::ParticipantCommissionList::Commission#status
         module Status
           extend GrowsurfRuby::Internal::Type::Enum

data/lib/growsurf_ruby/models/participant_payout_list.rb

@@ -79,12 +79,12 @@ module GrowsurfRuby
         # @!attribute exchange_rate_at
         #
         #   @return [Integer, nil]
-        optional :exchange_rate_at, Integer, api_name: :exchangeRateAt
+        optional :exchange_rate_at, Integer, api_name: :exchangeRateAt, nil?: true
 
         # @!attribute failed_at
         #
         #   @return [Integer, nil]
-        optional :failed_at, Integer, api_name: :failedAt
+        optional :failed_at, Integer, api_name: :failedAt, nil?: true
 
         # @!attribute fx_error
         #
@@ -94,7 +94,7 @@ module GrowsurfRuby
         # @!attribute issued_at
         #
         #   @return [Integer, nil]
-        optional :issued_at, Integer, api_name: :issuedAt
+        optional :issued_at, Integer, api_name: :issuedAt, nil?: true
 
         # @!attribute provider
         #
@@ -104,12 +104,12 @@ module GrowsurfRuby
         # @!attribute queued_at
         #
         #   @return [Integer, nil]
-        optional :queued_at, Integer, api_name: :queuedAt
+        optional :queued_at, Integer, api_name: :queuedAt, nil?: true
 
         # @!attribute reversed_at
         #
         #   @return [Integer, nil]
-        optional :reversed_at, Integer, api_name: :reversedAt
+        optional :reversed_at, Integer, api_name: :reversedAt, nil?: true
 
         # @!method initialize(id:, amount:, commission_ids:, created_at:, currency_iso:, participant_id:, status:, amount_in_campaign_currency: nil, campaign_currency_iso: nil, exchange_rate: nil, exchange_rate_at: nil, failed_at: nil, fx_error: nil, issued_at: nil, provider: nil, queued_at: nil, reversed_at: nil)
         #   @param id [String]

data/lib/growsurf_ruby/models.rb

@@ -41,6 +41,10 @@ module GrowsurfRuby
 
   AccountCreateParams = GrowsurfRuby::Models::AccountCreateParams
 
+  AnalyticsAvailability = GrowsurfRuby::Models::AnalyticsAvailability
+
+  AnalyticsUnavailableReason = GrowsurfRuby::Models::AnalyticsUnavailableReason
+
   AffiliateApplication = GrowsurfRuby::Models::AffiliateApplication
 
   AffiliateInvite = GrowsurfRuby::Models::AffiliateInvite
@@ -81,6 +85,9 @@ module GrowsurfRuby
   CampaignRetrieveAffiliateApplicationParams =
     GrowsurfRuby::Models::CampaignRetrieveAffiliateApplicationParams
 
+  CampaignRetrieveActivationAnalyticsParams =
+    GrowsurfRuby::Models::CampaignRetrieveActivationAnalyticsParams
+
   CampaignRetrieveAnalyticsParams = GrowsurfRuby::Models::CampaignRetrieveAnalyticsParams
 
   CampaignRetrieveParams = GrowsurfRuby::Models::CampaignRetrieveParams

data/lib/growsurf_ruby/resources/account.rb

@@ -4,19 +4,25 @@ module GrowsurfRuby
   module Resources
     class Account
       # Creates a new GrowSurf account. This is the only endpoint that does not require
-      # an API key. The response includes an API key for the new account, shown once in
-      # the response. The key is locked until the team owner's email address is
+      # an API key. Before calling it, an authorized account owner must review and
+      # approve GrowSurf's [Terms of Service](https://growsurf.com/terms) and [Privacy
+      # Policy](https://growsurf.com/privacy). The account starts a 14-day Business
+      # trial without a credit card. The response includes an API key for the new
+      # account, shown once in the response. The key is a secret: store it in a secret
+      # manager and do not put it in logs, screenshots, URLs, model context, analytics,
+      # or generated output. The key is locked until the team owner's email address is
       # verified: authenticated program and resource endpoints return a `403` with error
       # code `EMAIL_NOT_VERIFIED_ERROR` until then (resend the email via `POST
-      # /team/owner/verification-email`, then retry). A welcome email is sent to the
-      # address with the verification link and a set-password link for dashboard access.
-      # Accounts whose email is never verified are deleted automatically after 7 days.
-      # For security, the API key is rotated the first time the account owner signs in
-      # to the GrowSurf dashboard. Some actions (such as emailing participants)
-      # additionally require GrowSurf to verify the team first. By creating an account
-      # you agree, on behalf of the account holder, to GrowSurf's [Terms of
-      # Service](https://growsurf.com/terms) and [Privacy
-      # Policy](https://growsurf.com/privacy).
+      # /team/owner/verification-email`, then retry). Verification unlocks this same key
+      # - keep it and retry rather than requesting a replacement. A welcome email is
+      # sent to the address with the verification link and a set-password link for
+      # dashboard access. Accounts whose email is never verified are deleted
+      # automatically after 7 days. Separately, for security, the API key is replaced
+      # the first time the account owner signs in to the GrowSurf dashboard; email
+      # verification does not trigger that, and the previous key then returns a `403`
+      # with error code `NOT_AUTHORIZED_ERROR`. Some actions (such as emailing participants)
+      # additionally require GrowSurf to verify the team first. Calling this endpoint
+      # accepts those policies on the account holder's behalf.
       #
       # @overload create(email:, company: nil, first_name: nil, last_name: nil, request_options: {})
       #

data/lib/growsurf_ruby/resources/campaign/design.rb

@@ -7,8 +7,11 @@ module GrowsurfRuby
         # Retrieves a program's configured design fields: the dashboard Program Editor's **Design**
         # tab plus the payout-destination confirmation page copy configured from payout integration
         # cards. This includes the GrowSurf window layout, header, share channels and invites,
-        # signup form, portal and landing pages, theme styling, and referral or affiliate summary
-        # and status sections. The available fields depend on the program type.
+        # signup form, Resources presentation, portal and landing pages, theme styling, and referral
+        # or affiliate summary and status sections. `referredExperience` includes the Claim Offer Popup for both program
+        # types, with its colors under `theme.referredExperienceOfferPopup`.
+        # `participantAvatarStyle` is `CHARACTERS`, `INITIALS`, `ANIMALS`, or `GRADIENT`; missing or
+        # unknown values mean `INITIALS`.
         # `payoutDestinationConfirmation` is omitted when no confirmation fields are stored. Stored
         # `null` fields are returned as `null`; omitted and `null` fields use localized defaults.
         #
@@ -29,7 +32,8 @@ module GrowsurfRuby
         end
 
         # Updates a program's design configuration, including the payout-destination confirmation
-        # page copy configured from payout integration cards. Only the fields you send are changed;
+        # page copy and the Claim Offer Popup under `referredExperience`. Only the fields you send
+        # are changed;
         # anything you leave out is untouched (arrays such as `signup.fields` replace wholesale).
         # Unknown fields, fields not available for the program type, and invalid values return a
         # `400`. Landing-page custom code and JavaScript are not editable via the API.
@@ -38,8 +42,10 @@ module GrowsurfRuby
         #
         # @param id [String] GrowSurf program ID.
         #
-        # @param body [Hash{Symbol=>Object}] Partial design configuration to merge, such as
-        #   `{ payoutDestinationConfirmation: { headline: "Confirm your {{payoutProvider}} payout email" } }`.
+        # @param body [Hash{Symbol=>Object}] Partial design configuration to merge. `resources`
+        #   accepts `isPublicDisplayed`, `title`, `viewResourcesLinkText`, `backLinkText`,
+        #   `copyButtonText`, `copiedText`, `emptyState`, and `icon` (`type`: `DEFAULT`, `IMAGE`, or `NONE`, plus
+        #   `imageUrl` for `IMAGE`). Resource items use the Program Resources operations.
         #
         # @param request_options [GrowsurfRuby::RequestOptions, Hash{Symbol=>Object}, nil]
         #

data/lib/growsurf_ruby/resources/campaign/emails.rb

@@ -8,7 +8,8 @@ module GrowsurfRuby
         # Program Editor's **Emails** tab. Returns each editable email template
         # (`subject`, `preheader`, `body`, `isEnabled`) plus the `settings` block (sender,
         # contact, and design). The set of email templates returned depends on the program
-        # type (referral vs affiliate).
+        # type (referral vs affiliate). `offerClaimed` is available to both program types and sends
+        # while the Claim Offer Popup is enabled.
         #
         # @overload retrieve(id, request_options: {})
         #

data/lib/growsurf_ruby/resources/campaign/integrations.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module GrowsurfRuby
+  module Resources
+    class Campaign
+      class Integrations
+        # Lists every integration this program can connect, each with its current state.
+        # Integrations that do not apply to the program type are omitted (for example,
+        # Wise on a referral program). Read-only: connecting an integration is an OAuth or
+        # credential handshake completed in the GrowSurf dashboard, so it cannot be done
+        # over the API. `connected` means credentials are stored, `enabled` means the
+        # integration is switched on and working, and `autoDisabled` means GrowSurf
+        # switched it off after repeated delivery failures — its credentials are still
+        # stored, but it delivers nothing until it is reconnected in the dashboard.
+        #
+        # @overload list(id, request_options: {})
+        #
+        # @param id [String] GrowSurf program ID.
+        #
+        # @param request_options [GrowsurfRuby::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [GrowsurfRuby::Models::Campaign::IntegrationListResponse]
+        def list(id, params = {})
+          @client.request(
+            method: :get,
+            path: ["campaign/%1$s/integrations", id],
+            model: GrowsurfRuby::Models::Campaign::IntegrationListResponse,
+            options: params[:request_options]
+          )
+        end
+
+        # @api private
+        #
+        # @param client [GrowsurfRuby::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/growsurf_ruby/resources/campaign/participant.rb

@@ -8,7 +8,7 @@ module GrowsurfRuby
         #
         # @overload retrieve(participant_id_or_email, id:, request_options: {})
         #
-        # @param participant_id_or_email [String] GrowSurf participant ID or URL-encoded participant email address.
+        # @param participant_id_or_email [String] GrowSurf participant ID or unencoded participant email address (the SDK encodes it automatically).
         #
         # @param id [String] GrowSurf program ID.
         #
@@ -39,7 +39,7 @@ module GrowsurfRuby
         #
         # @overload update(participant_id_or_email, id:, affiliate_status: nil, email: nil, first_name: nil, last_name: nil, metadata: nil, notes: nil, referral_status: nil, referred_by: nil, unsubscribed: nil, vanity_keys: nil, request_options: {})
         #
-        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or URL-encoded participant email address.
+        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or unencoded participant email address (the SDK encodes it automatically).
         #
         # @param id [String] Path param: GrowSurf program ID.
         #
@@ -87,7 +87,7 @@ module GrowsurfRuby
         #
         # @overload delete(participant_id_or_email, id:, request_options: {})
         #
-        # @param participant_id_or_email [String] GrowSurf participant ID or URL-encoded participant email address.
+        # @param participant_id_or_email [String] GrowSurf participant ID or unencoded participant email address (the SDK encodes it automatically).
         #
         # @param id [String] GrowSurf program ID.
         #
@@ -200,7 +200,7 @@ module GrowsurfRuby
         #
         # @overload list_commissions(participant_id_or_email, id:, limit: nil, next_id: nil, status: nil, request_options: {})
         #
-        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or URL-encoded participant email address.
+        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or unencoded participant email address (the SDK encodes it automatically).
         #
         # @param id [String] Path param: GrowSurf program ID.
         #
@@ -236,7 +236,7 @@ module GrowsurfRuby
         #
         # @overload list_payouts(participant_id_or_email, id:, limit: nil, next_id: nil, status: nil, request_options: {})
         #
-        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or URL-encoded participant email address.
+        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or unencoded participant email address (the SDK encodes it automatically).
         #
         # @param id [String] Path param: GrowSurf program ID.
         #
@@ -271,7 +271,7 @@ module GrowsurfRuby
         #
         # @overload list_referrals(participant_id_or_email, id:, desc: nil, email: nil, first_name: nil, last_name: nil, limit: nil, next_id: nil, offset: nil, referral_status: nil, sort_by: nil, request_options: {})
         #
-        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or URL-encoded participant email address.
+        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or unencoded participant email address (the SDK encodes it automatically).
         #
         # @param id [String] Path param: GrowSurf program ID.
         #
@@ -324,7 +324,7 @@ module GrowsurfRuby
         #
         # @overload list_rewards(participant_id_or_email, id:, limit: nil, next_id: nil, request_options: {})
         #
-        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or URL-encoded participant email address.
+        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or unencoded participant email address (the SDK encodes it automatically).
         #
         # @param id [String] Path param: GrowSurf program ID.
         #
@@ -360,9 +360,9 @@ module GrowsurfRuby
         # de-duplicated — without one, a resent sale would create a second commission.
         # Reuse the same identifier(s) when refunding.
         #
-        # @overload record_transaction(participant_id_or_email, id:, 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: {})
+        # @overload record_transaction(participant_id_or_email, id:, 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 participant_id_or_email [String] Path param: GrowSurf participant ID or URL-encoded participant email address.
+        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or unencoded participant email address (the SDK encodes it automatically).
         #
         # @param id [String] Path param: GrowSurf program ID.
         #
@@ -437,11 +437,12 @@ module GrowsurfRuby
         # and reverses or adjusts the referrer's commission. The inverse of Record
         # Affiliate Transaction. Identify the original transaction with the same
         # identifier(s) you sent when recording it. Commissions already paid out to the
-        # affiliate are not clawed back; the amendment is recorded for tax reporting only.
+        # affiliate are not clawed back. The amendment still updates the sale revenue used
+        # in program reporting; full refunds and chargebacks also update tax reporting.
         #
-        # @overload refund_transaction(participant_id_or_email, id:, 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: {})
+        # @overload refund_transaction(participant_id_or_email, id:, 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, payment_provider: nil, test_mode: nil, request_options: {})
         #
-        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or URL-encoded participant email address.
+        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or unencoded participant email address (the SDK encodes it automatically).
         #
         # @param id [String] Path param: GrowSurf program ID.
         #
@@ -501,7 +502,7 @@ module GrowsurfRuby
         #
         # @overload send_invites(participant_id_or_email, id:, email_addresses:, message_text:, subject_text:, request_options: {})
         #
-        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or URL-encoded participant email address.
+        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or unencoded participant email address (the SDK encodes it automatically).
         #
         # @param id [String] Path param: GrowSurf program ID.
         #
@@ -543,7 +544,7 @@ module GrowsurfRuby
         #
         # @overload trigger_referral(participant_id_or_email, id:, delay_in_days: nil, request_options: {})
         #
-        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or URL-encoded participant email address.
+        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or unencoded participant email address (the SDK encodes it automatically).
         #
         # @param id [String] Path param: GrowSurf program ID.
         #
@@ -577,7 +578,7 @@ module GrowsurfRuby
         #
         # @overload cancel_delayed_referral(participant_id_or_email, id:, request_options: {})
         #
-        # @param participant_id_or_email [String] GrowSurf participant ID or URL-encoded participant email address.
+        # @param participant_id_or_email [String] GrowSurf participant ID or unencoded participant email address (the SDK encodes it automatically).
         #
         # @param id [String] GrowSurf program ID.
         #
@@ -611,7 +612,7 @@ module GrowsurfRuby
         #
         # @overload email(participant_id_or_email, id:, body: nil, email_type: nil, preheader: nil, subject: nil, request_options: {})
         #
-        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or URL-encoded participant email address.
+        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or unencoded participant email address (the SDK encodes it automatically).
         #
         # @param id [String] Path param: GrowSurf program ID.
         #
@@ -648,7 +649,7 @@ module GrowsurfRuby
         #
         # @overload list_activity_logs(participant_id_or_email, id:, limit: nil, offset: nil, request_options: {})
         #
-        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or URL-encoded participant email address.
+        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or unencoded participant email address (the SDK encodes it automatically).
         #
         # @param id [String] Path param: GrowSurf program ID.
         #
@@ -686,24 +687,26 @@ module GrowsurfRuby
         # commission, and payout metrics for affiliate programs). Pass `include=email`
         # for `sent` (accepted for delivery), `delivered`, `opened`, `clicked`,
         # `bounced`, and `spamComplaints` metrics attributed to this participant,
-        # including invitations they sent. Use `include=email,series` to include the
-        # same counts in each UTC series bucket.
+        # including invitations they sent. Add `activation` for the cohort anchor and
+        # covered first milestones. Use `include=activation,series` to add covered portal
+        # views and share actions to each series bucket. Unknown history stays `null` with
+        # an explicit coverage state.
         #
         # @overload retrieve_analytics(participant_id_or_email, id:, days: nil, end_date: nil, include: nil, interval: nil, start_date: nil, request_options: {})
         #
-        # @param participant_id_or_email [String] GrowSurf participant ID or URL-encoded participant email address.
+        # @param participant_id_or_email [String] GrowSurf participant ID or unencoded participant email address (the SDK encodes it automatically).
         #
         # @param id [String] GrowSurf program ID.
         #
-        # @param days [Integer] Last number of days to retrieve analytics for. Defaults to 365. Maximum 1825.
+        # @param days [Integer] Last number of days for optional `series` and `email` analytics. Defaults to 365. Maxi
         #
-        # @param end_date [Integer] End date of the analytics timeframe as a Unix timestamp in milliseconds. Require
+        # @param end_date [Integer] End of a custom `series` and `email` analytics window as a Unix timestamp in milli
         #
         # @param include [String] Comma-separated optional data. `series` returns this participant's own activity
         #
         # @param interval [Symbol, GrowsurfRuby::Models::Campaign::ParticipantRetrieveAnalyticsParams::Interval] Bucket size for the `series` (only used when `include` contains `series`).
         #
-        # @param start_date [Integer] Start date of the analytics timeframe as a Unix timestamp in milliseconds. Requi
+        # @param start_date [Integer] Start of a custom `series` and `email` analytics window as a Unix timestamp in mi
         #
         # @param request_options [GrowsurfRuby::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -735,7 +738,7 @@ module GrowsurfRuby
         #
         # @overload get_payout_destination(participant_id_or_email, id:, request_options: {})
         #
-        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or URL-encoded participant email address.
+        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or unencoded participant email address (the SDK encodes it automatically).
         #
         # @param id [String] Path param: GrowSurf program ID.
         #
@@ -765,7 +768,7 @@ module GrowsurfRuby
         #
         # @overload request_payout_destination_confirmation(participant_id_or_email, id:, provider:, request_options: {})
         #
-        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or URL-encoded participant email address.
+        # @param participant_id_or_email [String] Path param: GrowSurf participant ID or unencoded participant email address (the SDK encodes it automatically).
         #
         # @param id [String] Path param: GrowSurf program ID.
         #

data/lib/growsurf_ruby/resources/campaign/program_resources.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module GrowsurfRuby
+  module Resources
+    class Campaign
+      # Program Resource management and secure FILE upload operations.
+      class ProgramResources
+        def list(id, params = {})
+          @client.request(
+            method: :get,
+            path: ["campaign/%1$s/resources", id],
+            model: GrowsurfRuby::Campaign::ProgramResourceListResponse,
+            options: params[:request_options]
+          )
+        end
+
+        def create(id, params)
+          parsed, options = GrowsurfRuby::Campaign::ProgramResourceCreateParams.dump_request(params)
+          validate_write!(parsed, creating: true)
+          @client.request(
+            method: :post,
+            path: ["campaign/%1$s/resources", id],
+            body: parsed,
+            model: GrowsurfRuby::Campaign::ProgramResource,
+            options: options
+          )
+        end
+
+        def update(resource_id, params)
+          parsed, options = GrowsurfRuby::Campaign::ProgramResourceUpdateParams.dump_request(params)
+          id = parsed.delete(:id) { raise ArgumentError.new("missing required path argument id") }
+          validate_write!(parsed, creating: false)
+          @client.request(
+            method: :patch,
+            path: ["campaign/%1$s/resources/%2$s", id, resource_id],
+            body: parsed,
+            model: GrowsurfRuby::Campaign::ProgramResource,
+            options: options
+          )
+        end
+
+        def delete(resource_id, params)
+          parsed, options = GrowsurfRuby::Campaign::ProgramResourceDeleteParams.dump_request(params)
+          id = parsed.delete(:id) { raise ArgumentError.new("missing required path argument id") }
+          @client.request(
+            method: :delete,
+            path: ["campaign/%1$s/resources/%2$s", id, resource_id],
+            model: GrowsurfRuby::Campaign::DeleteProgramResourceResponse,
+            options: options
+          )
+        end
+
+        def create_upload_ticket(id, params)
+          parsed, options = GrowsurfRuby::Campaign::ProgramResourceUploadTicketParams.dump_request(params)
+          file_name = parsed[:fileName]
+          unless file_name.is_a?(String) && file_name.length.between?(1, 120)
+            raise ArgumentError.new("Program Resource file_name must contain 1 through 120 characters")
+          end
+          @client.request(
+            method: :post,
+            path: ["campaign/%1$s/resource-upload-tickets", id],
+            body: parsed,
+            model: GrowsurfRuby::Campaign::ProgramResourceUploadTicket,
+            options: options
+          )
+        end
+
+        # @api private
+        def initialize(client:)
+          @client = client
+        end
+
+        private
+
+        # Rejects Resource field combinations excluded by the public REST contract.
+        def validate_write!(params, creating:)
+          if !creating && params.empty?
+            raise ArgumentError.new("Program Resource update requires at least one field")
+          end
+
+          position = params[:position]
+          if params.key?(:position) && (!position.is_a?(Integer) || !position.between?(0, 99))
+            raise ArgumentError.new("Program Resource position must be an integer from 0 through 99")
+          end
+
+          has_upload_ticket = params.key?(:uploadTicket)
+          has_upload_result = params.key?(:uploadResult)
+          if has_upload_ticket != has_upload_result
+            raise ArgumentError.new("upload_ticket and upload_result must be supplied together")
+          end
+
+          supplied_types = []
+          supplied_types << :LINK if params.key?(:url)
+          supplied_types << :TEXT if params.key?(:text)
+          supplied_types << :FILE if has_upload_ticket
+          raise ArgumentError.new("send content fields for only one Program Resource type") if supplied_types.length > 1
+
+          type = params[:type]
+          if supplied_types.any? && !type.nil? && supplied_types.first != type
+            raise ArgumentError.new("content fields must match the selected Program Resource type")
+          end
+          if !creating && !type.nil? && supplied_types != [type]
+            raise ArgumentError.new("changing a Program Resource type requires its replacement content")
+          end
+          return unless creating && (supplied_types.empty? || supplied_types.first != type)
+
+          raise ArgumentError.new("create requires content fields for the selected Program Resource type")
+        end
+      end
+    end
+  end
+end

data/lib/growsurf_ruby/resources/campaign/rewards.rb

@@ -28,15 +28,16 @@ module GrowsurfRuby
         # The reward type must be compatible with the program type (affiliate programs
         # support only `AFFILIATE` rewards; referral programs support all other types).
         # Enabling an active reward of a type automatically enables that reward type on
-        # the program.
+        # the program. For an affiliate reward, `commissionStructure.event: LEAD`
+        # requires a `FIXED` commission with a positive `amount`.
         #
-        # @overload create(id, type:, commission_structure: nil, conversions_required: nil, coupon_code: nil, description: nil, image_url: nil, is_unlimited: nil, is_visible: nil, limit: nil, limit_duration: nil, metadata: nil, next_milestone_prefix: nil, next_milestone_suffix: nil, number_of_winners: nil, order: nil, referral_coupon_code: nil, referral_description: nil, referred_reward_upfront: nil, referred_value: nil, title: nil, value: nil, request_options: {})
+        # @overload create(id, type:, commission_structure: nil, conversions_required: nil, coupon_code: nil, description: nil, event: nil, image_url: nil, is_unlimited: nil, is_visible: nil, limit: nil, limit_duration: nil, metadata: nil, next_milestone_prefix: nil, next_milestone_suffix: nil, number_of_winners: nil, order: nil, referral_coupon_code: nil, referral_description: nil, referred_reward_upfront: nil, referred_value: nil, title: nil, value: nil, request_options: {})
         #
         # @param id [String] Path param: GrowSurf program ID.
         #
         # @param type [Symbol, GrowsurfRuby::Models::Campaign::RewardCreateParams::Type] Body param: The reward type. Immutable after creation.
         #
-        # @param commission_structure [GrowsurfRuby::Models::CommissionStructure] Body param
+        # @param commission_structure [GrowsurfRuby::Models::CommissionStructure] Body param: The affiliate commission structure. Required when creating an `AFFILIATE` reward. A `FIXED` commission requires `amount`; a `PERCENT` commission requires `percent`.
         #
         # @param conversions_required [Integer] Body param
         #
@@ -44,6 +45,8 @@ module GrowsurfRuby
         #
         # @param description [String] Body param
         #
+        # @param event [Symbol, GrowsurfRuby::Models::Campaign::RewardCreateParams::Event] Body param: The referral event that earns this Campaign Reward. Use `LEAD` or `CONVERSION`. `LEAD` requires the program installation's `referralTrigger` to be `CUSTOM`. This field applies only to `SINGLE_SIDED`, `DOUBLE_SIDED`, and `MILESTONE` rewards. When omitted, it defaults to `CONVERSION`.
+        #
         # @param image_url [String] Body param
         #
         # @param is_unlimited [Boolean] Body param: Whether the reward can be earned an unlimited number of times. Defaul
@@ -96,15 +99,16 @@ module GrowsurfRuby
         # immutable and cannot be changed. When the update replaces `metadata`, renamed
         # keys automatically rewrite any `{{campaignReward[…]}}` references in campaign
         # copy; removing a key that campaign copy still references returns a `409` listing
-        # the referencing fields.
+        # the referencing fields. For an affiliate reward, `commissionStructure.event:
+        # LEAD` requires a `FIXED` commission with a positive `amount`.
         #
-        # @overload update(campaign_reward_id, id:, commission_structure: nil, conversions_required: nil, coupon_code: nil, description: nil, image_url: nil, is_unlimited: nil, is_visible: nil, limit: nil, limit_duration: nil, metadata: nil, next_milestone_prefix: nil, next_milestone_suffix: nil, number_of_winners: nil, order: nil, referral_coupon_code: nil, referral_description: nil, referred_reward_upfront: nil, referred_value: nil, title: nil, value: nil, request_options: {})
+        # @overload update(campaign_reward_id, id:, commission_structure: nil, conversions_required: nil, coupon_code: nil, description: nil, event: nil, image_url: nil, is_unlimited: nil, is_visible: nil, limit: nil, limit_duration: nil, metadata: nil, next_milestone_prefix: nil, next_milestone_suffix: nil, number_of_winners: nil, order: nil, referral_coupon_code: nil, referral_description: nil, referred_reward_upfront: nil, referred_value: nil, title: nil, value: nil, request_options: {})
         #
         # @param campaign_reward_id [String] Path param: Campaign reward ID.
         #
         # @param id [String] Path param: GrowSurf program ID.
         #
-        # @param commission_structure [GrowsurfRuby::Models::CommissionStructure] Body param
+        # @param commission_structure [GrowsurfRuby::Models::CommissionStructure] Body param: The affiliate commission structure. A `FIXED` commission requires `amount`; a `PERCENT` commission requires `percent`.
         #
         # @param conversions_required [Integer] Body param
         #
@@ -112,6 +116,8 @@ module GrowsurfRuby
         #
         # @param description [String] Body param
         #
+        # @param event [Symbol, GrowsurfRuby::Models::Campaign::RewardUpdateParams::Event] Body param: The referral event that earns this Campaign Reward. Use `LEAD` or `CONVERSION`. `LEAD` requires the program installation's `referralTrigger` to be `CUSTOM`. This field applies only to `SINGLE_SIDED`, `DOUBLE_SIDED`, and `MILESTONE` rewards. When omitted, the stored event is preserved.
+        #
         # @param image_url [String] Body param
         #
         # @param is_unlimited [Boolean] Body param: Whether the reward can be earned an unlimited number of times. Defaul