growsurf-ruby 1.2.0 → 1.3.0

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

@@ -4,12 +4,11 @@ module GrowsurfRuby
   module Resources
     class Campaign
       class Options
-        # Retrieves a program's options configuration — the same surface as the dashboard
-        # Program Editor's **Options** tab (fraud/reCAPTCHA, tax documentation,
-        # notification emails, and other program settings).
-        #
-        # To see the full object with every field and its current value, `GET` this
-        # resource, then `PATCH` back only the fields you want to change.
+        # Retrieves a program's options — the same surface as the dashboard Program
+        # Editor's **Options** tab. Includes reward/fraud approval, anti-fraud lists +
+        # toggles, referral cookie/credit windows, reCAPTCHA, affiliate enrollment +
+        # application review, payout threshold + tax settings (affiliate only), and
+        # notification-email settings. `fraud.recaptcha.secretKey` is never returned.
         #
         # @overload retrieve(id, request_options: {})
         #
@@ -27,13 +26,12 @@ module GrowsurfRuby
           )
         end
 
-        # Updates a program's options configuration. Only the fields you send are changed;
-        # anything you leave out is untouched. Unknown fields and invalid values return a
-        # `400`.
-        #
-        # The request body is a partial {CampaignOptions} object. To see the full object
-        # with every field and its current value, `GET` this resource, then `PATCH` back
-        # only the fields you want to change.
+        # Updates a program's options. Only the fields you send are changed. Some fields
+        # are program-type specific (`requireManualRewardApproval`/`autoFulfillRewards`
+        # are referral-only; `affiliateApplicationMode`/`affiliateReapplicationPolicy`
+        # and `payoutThreshold`/`taxDocumentation` are affiliate-only, and affiliate
+        # programs require `requireParticipantAuth: true`). `fraud.recaptcha.secretKey`
+        # is write-only. `referralCreditWindowDays: null` means "never expires".
         #
         # @overload update(id, body, request_options: {})
         #

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

@@ -31,14 +31,20 @@ module GrowsurfRuby
           )
         end
 
-        # Updates a participant by GrowSurf participant ID or email address.
+        # Updates a participant by GrowSurf participant ID or email address. For affiliate
+        # programs, set `affiliateStatus` to `APPROVED`, `SUSPENDED`, or `BANNED`.
+        # `APPROVED` enrolls the participant as an affiliate. `SUSPENDED` and `BANNED`
+        # require an existing affiliate. This endpoint does not accept `isAffiliate`, and
+        # affiliate enrollment cannot be removed through REST.
         #
-        # @overload update(participant_id_or_email, id:, email: nil, first_name: nil, last_name: nil, metadata: nil, notes: nil, paypal_email: nil, referral_status: nil, referred_by: nil, unsubscribed: nil, vanity_keys: nil, request_options: {})
+        # @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 id [String] Path param: GrowSurf program ID.
         #
+        # @param affiliate_status [Symbol, GrowsurfRuby::Models::Campaign::ParticipantUpdateParams::AffiliateStatus] Body param: Affiliate programs only. Sets the affiliate status. `APPROVED` also enrolls a participant who is not yet an affiliate. `SUSPENDED` and `BANNED` are rejected for non-affiliates.
+        #
         # @param email [String] Body param
         #
         # @param first_name [String] Body param
@@ -49,8 +55,6 @@ module GrowsurfRuby
         #
         # @param notes [String] Body param: Freeform internal notes about the participant (internal only, never ex
         #
-        # @param paypal_email [String] Body param: The participant's PayPal email address, used for affiliate payouts.
-        #
         # @param referral_status [Symbol, GrowsurfRuby::Models::Campaign::ParticipantUpdateParams::ReferralStatus] Body param
         #
         # @param referred_by [String] Body param
@@ -110,12 +114,12 @@ module GrowsurfRuby
         # {GrowsurfRuby::Models::Campaign::ParticipantBulkDeleteParams} for more details.
         #
         # Deletes a list of participants from a program in one request. Each entry in
-        # `participants` is a GrowSurf participant ID or an email address (mixed lists
-        # are allowed). Up to `200` entries per request — chunk larger lists across
-        # multiple calls. The response reports a per-row `status` for every submitted
-        # entry, so a `200` can include rows that were `NOT_FOUND` or failed. Deletion
-        # is permanent and removes the participants' referrals, rewards, commissions,
-        # and payout records.
+        # `participants` is a GrowSurf participant ID or an email address (mixed lists are
+        # allowed). Up to `200` entries per request — chunk larger lists across multiple
+        # calls. The response reports a per-row `status` for every submitted entry, so a
+        # `200` can include rows that were `NOT_FOUND` or failed. Deletion is permanent
+        # and removes the participants' referrals, rewards, commissions, and payout
+        # records.
         #
         # @overload bulk_delete(id, participants:, request_options: {})
         #
@@ -143,9 +147,15 @@ module GrowsurfRuby
         # {GrowsurfRuby::Models::Campaign::ParticipantAddParams} for more details.
         #
         # Adds a new participant to the program. If the email already exists, the existing
-        # participant is returned.
+        # participant is returned unchanged. For affiliate programs, set `isAffiliate` to
+        # `true` to enroll a new participant as an approved affiliate or `false` to create
+        # a non-affiliate. If you omit `isAffiliate`, a valid `referredBy` creates a
+        # referred non-affiliate; without a valid referrer, the new participant is enrolled
+        # as an approved affiliate. You can send a valid `referredBy` with
+        # `isAffiliate: true` to keep the referral attribution and enroll the participant
+        # as an affiliate.
         #
-        # @overload add(id, email:, fingerprint: nil, first_name: nil, ip_address: nil, last_name: nil, metadata: nil, mobile_instance_id: nil, referral_status: nil, referred_by: nil, request_options: {})
+        # @overload add(id, email:, fingerprint: nil, first_name: nil, ip_address: nil, is_affiliate: nil, last_name: nil, metadata: nil, mobile_instance_id: nil, referral_status: nil, referred_by: nil, request_options: {})
         #
         # @param id [String] GrowSurf program ID.
         #
@@ -157,6 +167,8 @@ module GrowsurfRuby
         #
         # @param ip_address [String]
         #
+        # @param is_affiliate [Boolean] Affiliate programs only. Controls affiliate enrollment for a new participant. `true` enrolls the participant with `affiliateStatus: APPROVED`; `false` creates a non-affiliate without `affiliateStatus`. Existing participants are returned unchanged.
+        #
         # @param last_name [String]
         #
         # @param metadata [Hash{Symbol=>Object}] Shallow custom metadata object.
@@ -183,7 +195,8 @@ module GrowsurfRuby
           )
         end
 
-        # Retrieves a paged list of commissions earned by a participant.
+        # **Affiliate programs only.** Retrieves a paged list of commissions earned by a
+        # participant.
         #
         # @overload list_commissions(participant_id_or_email, id:, limit: nil, next_id: nil, status: nil, request_options: {})
         #
@@ -218,7 +231,8 @@ module GrowsurfRuby
           )
         end
 
-        # Retrieves a paged list of payouts that belong to a participant.
+        # **Affiliate programs only.** Retrieves a paged list of payouts that belong to a
+        # participant.
         #
         # @overload list_payouts(participant_id_or_email, id:, limit: nil, next_id: nil, status: nil, request_options: {})
         #
@@ -339,15 +353,12 @@ module GrowsurfRuby
           )
         end
 
-        # Records a sale made by a referred customer and generates affiliate commissions
-        # for their referrer when applicable.
-        #
-        # At least one transaction identifier is required: one of +external_id+,
-        # +transaction_id+, +order_id+, +payment_id+, +invoice_id+, +payment_intent_id+,
-        # or +charge_id+. +customer_id+ and +subscription_id+ do not count, since they
-        # identify the customer or subscription rather than the specific transaction.
-        # Without an identifier, resending the same sale creates a duplicate commission
-        # and double-pays the referrer; the server rejects such requests with HTTP 400.
+        # **Affiliate programs only.** Records a sale made by a referred customer and
+        # generates affiliate commissions for their referrer when applicable. Requires at
+        # least one transaction identifier (externalId, transactionId, orderId, paymentId,
+        # invoiceId, paymentIntentId, or chargeId) so repeated requests can be
+        # 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: {})
         #
@@ -421,9 +432,12 @@ module GrowsurfRuby
           )
         end
 
-        # Records an amendment (refund, partial refund, refund cancellation, or
-        # chargeback) against a previously recorded transaction and reverses or adjusts
-        # the referrer's commission.
+        # **Affiliate programs only.** Records an amendment (refund, partial refund,
+        # refund cancellation, or chargeback) against a previously recorded transaction
+        # 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.
         #
         # @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: {})
         #
@@ -482,7 +496,7 @@ module GrowsurfRuby
         end
 
         # Sends email invites on behalf of a participant to a list of email addresses.
-        # Sending invites via the API requires a verified custom email domain on the
+        # Sending invites via the API requires a **verified custom email domain** on the
         # program; the request fails until one is verified.
         #
         # @overload send_invites(participant_id_or_email, id:, email_addresses:, message_text:, subject_text:, request_options: {})
@@ -522,7 +536,10 @@ module GrowsurfRuby
         # details.
         #
         # Triggers referral credit for an existing referred participant by GrowSurf
-        # participant ID or email address.
+        # participant ID or email address. Optionally pass `delayInDays` to hold the
+        # credit for a number of days before it is awarded (for example, to cover your own
+        # refund window). A delayed trigger can be cancelled before it is awarded with the
+        # Cancel delayed referral trigger request (DELETE on this same path).
         #
         # @overload trigger_referral(participant_id_or_email, id:, delay_in_days: nil, request_options: {})
         #
@@ -552,8 +569,11 @@ module GrowsurfRuby
           )
         end
 
-        # Cancels a pending delayed referral trigger for an existing referred participant
-        # by GrowSurf participant ID or email address.
+        # Cancels a pending delayed referral trigger for a participant (the companion to a
+        # delayed Trigger referral request). Use this to undo a scheduled referral credit
+        # before it is awarded, for example when a refund occurs inside your refund
+        # window. If the participant has no pending delayed trigger, `success` is returned
+        # as `false`.
         #
         # @overload cancel_delayed_referral(participant_id_or_email, id:, request_options: {})
         #
@@ -580,15 +600,14 @@ module GrowsurfRuby
           )
         end
 
-        # Sends an email to a participant. Provide EITHER `email_type` to trigger one of the
-        # program's configured email templates, OR `subject` + `body` for a free-form email.
-        # Free-form emails are sent with the same compliance handling (company name,
-        # postal address, and an unsubscribe link are added automatically, and unsubscribed
-        # participants are suppressed). Sending requires the team to be verified by
-        # GrowSurf. Requires a verified custom email domain on the program (set up
-        # in Campaign Editor > 3. Emails > Email Settings). Returns `400` until one is
-        # verified.
-        # The email is accepted for delivery.
+        # Sends an email to a participant. Provide EITHER `emailType` to trigger one of
+        # the program's configured email templates, OR `subject` + `body` for a free-form
+        # email. Free-form emails are sent with the same compliance handling (company
+        # name, postal address, and an unsubscribe link are added automatically, and
+        # unsubscribed participants are suppressed). Sending requires the team to be
+        # verified by GrowSurf. Requires a **verified custom email domain** on the program
+        # (which can be completed in *Campaign Editor > 3. Emails > Email Settings*).
+        # Returns `400` until one is verified. The email is accepted for delivery.
         #
         # @overload email(participant_id_or_email, id:, body: nil, email_type: nil, preheader: nil, subject: nil, request_options: {})
         #
@@ -624,7 +643,8 @@ module GrowsurfRuby
           )
         end
 
-        # Returns a participant's activity logs, most recent first (offset/limit paginated).
+        # Returns a participant's activity logs, most recent first (offset/limit
+        # paginated).
         #
         # @overload list_activity_logs(participant_id_or_email, id:, limit: nil, offset: nil, request_options: {})
         #
@@ -662,8 +682,12 @@ module GrowsurfRuby
         # details.
         #
         # Retrieves analytics for a single participant — all-time engagement counters,
-        # leaderboard ranks, and per-channel share counts (plus affiliate money metrics for
-        # affiliate programs). Useful for segmenting and re-engaging participants.
+        # leaderboard ranks, and per-channel share counts (plus affiliate revenue,
+        # 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.
         #
         # @overload retrieve_analytics(participant_id_or_email, id:, days: nil, end_date: nil, include: nil, interval: nil, start_date: nil, request_options: {})
         #
@@ -675,9 +699,9 @@ module GrowsurfRuby
         #
         # @param end_date [Integer] End date of the analytics timeframe as a Unix timestamp in milliseconds. Require
         #
-        # @param include [Symbol, GrowsurfRuby::Models::Campaign::ParticipantRetrieveAnalyticsParams::Include] Set to `series` to also return this participant's own activity per period.
+        # @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 with `include=series`). Defaults to `day`.
+        # @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
         #
@@ -702,6 +726,76 @@ module GrowsurfRuby
           )
         end
 
+        # Returns a participant's payout-destination status across every payout provider
+        # enabled for the program (PayPal and/or Wise). For each provider it reports the
+        # current status, the confirmed claim email, the legal recipient type, and — when a
+        # delivery bounced or a recipient was invalidated — the repair reason.
+        # `activeProvider` is the provider that currently gets paid, or `null` until the
+        # participant confirms one.
+        #
+        # @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 id [String] Path param: GrowSurf program ID.
+        #
+        # @param request_options [GrowsurfRuby::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [GrowsurfRuby::Models::Campaign::ParticipantGetPayoutDestinationResponse]
+        #
+        # @see GrowsurfRuby::Models::Campaign::ParticipantGetPayoutDestinationParams
+        def get_payout_destination(participant_id_or_email, params)
+          parsed, options = GrowsurfRuby::Campaign::ParticipantGetPayoutDestinationParams.dump_request(params)
+          id =
+            parsed.delete(:id) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          @client.request(
+            method: :get,
+            path: ["campaign/%1$s/participant/%2$s/payout-destination", id, participant_id_or_email],
+            model: GrowsurfRuby::Models::Campaign::ParticipantGetPayoutDestinationResponse,
+            options: options
+          )
+        end
+
+        # Sends the participant a one-time link to confirm their payout destination for
+        # the chosen provider. Only the participant can open the link and confirm — this
+        # endpoint just triggers the message. The provider must be enabled for the
+        # program.
+        #
+        # @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 id [String] Path param: GrowSurf program ID.
+        #
+        # @param provider [Symbol, GrowsurfRuby::Models::Campaign::ParticipantRequestPayoutDestinationConfirmationParams::Provider] Body param: The payout provider the participant should confirm a destination for.
+        #
+        # @param request_options [GrowsurfRuby::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [GrowsurfRuby::Models::Campaign::ParticipantRequestPayoutDestinationConfirmationResponse]
+        #
+        # @see GrowsurfRuby::Models::Campaign::ParticipantRequestPayoutDestinationConfirmationParams
+        def request_payout_destination_confirmation(participant_id_or_email, params)
+          parsed, options =
+            GrowsurfRuby::Campaign::ParticipantRequestPayoutDestinationConfirmationParams.dump_request(params)
+          id =
+            parsed.delete(:id) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          @client.request(
+            method: :post,
+            path: [
+              "campaign/%1$s/participant/%2$s/payout-destination/request-confirmation",
+              id,
+              participant_id_or_email
+            ],
+            body: parsed,
+            model: GrowsurfRuby::Models::Campaign::ParticipantRequestPayoutDestinationConfirmationResponse,
+            options: options
+          )
+        end
+
         # @api private
         #
         # @param client [GrowsurfRuby::Client]

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

@@ -33,8 +33,9 @@ module GrowsurfRuby
           )
         end
 
-        # Approves a manually approved reward earned by a participant. Requires
-        # `reward:write`. Passing `fulfill: true` also requires `reward:fulfill`.
+        # Approves a manually approved reward earned by a participant. This requires
+        # `reward:write`. When the request also sets `fulfill` to `true`, it additionally
+        # requires `reward:fulfill`.
         #
         # @overload approve(reward_id, id:, fulfill: nil, request_options: {})
         #
@@ -64,7 +65,7 @@ module GrowsurfRuby
           )
         end
 
-        # Marks an approved participant reward as fulfilled. Requires `reward:fulfill`.
+        # Marks an approved participant reward as fulfilled.
         #
         # @overload fulfill(reward_id, id:, request_options: {})
         #

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

@@ -4,7 +4,9 @@ module GrowsurfRuby
   module Resources
     class Campaign
       class Rewards
-        # Retrieves the rewards configured for a program.
+        # Retrieves the list of a program's configured rewards (`CampaignReward`s) — the
+        # same set embedded in the `rewards` array of the campaign response. Delete a
+        # reward with `DELETE /campaign/{id}/reward-configs/{campaignRewardId}`.
         #
         # @overload list(id, request_options: {})
         #
@@ -22,8 +24,11 @@ module GrowsurfRuby
           )
         end
 
-        # Creates a reward for a program. The reward `type` must be compatible with the
-        # program type.
+        # Creates a new campaign reward (`CampaignReward`) with a GrowSurf-assigned ID.
+        # 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.
         #
         # @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: {})
         #
@@ -65,7 +70,7 @@ module GrowsurfRuby
         #
         # @param referred_reward_upfront [Boolean] Body param
         #
-        # @param referred_value [GrowsurfRuby::Models::RewardTaxValuation] Body param: Tax valuation for the referred friend's side of a double-sided rewa
+        # @param referred_value [GrowsurfRuby::Models::RewardTaxValuation] Body param: Tax treatment override for the referred friend's side of a double-sided rewa
         #
         # @param title [String] Body param
         #
@@ -87,8 +92,11 @@ module GrowsurfRuby
           )
         end
 
-        # Updates an existing campaign reward. Only the fields you send are changed;
-        # `type` is immutable and must not be supplied.
+        # Updates an existing campaign reward (`CampaignReward`). The reward `type` is
+        # 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.
         #
         # @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: {})
         #
@@ -130,7 +138,7 @@ module GrowsurfRuby
         #
         # @param referred_reward_upfront [Boolean] Body param
         #
-        # @param referred_value [GrowsurfRuby::Models::RewardTaxValuation] Body param: Tax valuation for the referred friend's side of a double-sided rewa
+        # @param referred_value [GrowsurfRuby::Models::RewardTaxValuation] Body param: Tax treatment override for the referred friend's side of a double-sided rewa
         #
         # @param title [String] Body param
         #
@@ -156,7 +164,11 @@ module GrowsurfRuby
           )
         end
 
-        # Deletes a campaign reward.
+        # Deletes a campaign reward (`CampaignReward`). The reward is deactivated, removed
+        # from the program's reward set, and any connected upfront-discount coupons are
+        # cleaned up. If campaign copy still references any of the reward's metadata keys
+        # via `{{campaignReward[…]}}` tokens, the delete returns a `409` listing the
+        # referencing fields — update those fields first.
         #
         # @overload delete(campaign_reward_id, id:, request_options: {})
         #