growsurf-ruby 0.8.0 → 1.1.0

data/rbi/growsurf_ruby/resources/campaign/participant.rbi

@@ -30,6 +30,8 @@ module GrowsurfRuby
             first_name: String,
             last_name: String,
             metadata: T::Hash[Symbol, T.anything],
+            notes: String,
+            paypal_email: String,
             referral_status:
               GrowsurfRuby::Campaign::ParticipantUpdateParams::ReferralStatus::OrSymbol,
             referred_by: String,
@@ -51,6 +53,11 @@ module GrowsurfRuby
           last_name: nil,
           # Body param: Shallow custom metadata object.
           metadata: nil,
+          # Body param: Freeform internal notes about the participant (internal only, never
+          # exposed to participants).
+          notes: nil,
+          # Body param: The participant's PayPal email address, used for affiliate payouts.
+          paypal_email: nil,
           # Body param
           referral_status: nil,
           # Body param
@@ -80,6 +87,32 @@ module GrowsurfRuby
         )
         end
 
+        # 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.
+        sig do
+          params(
+            id: String,
+            participants: T::Array[String],
+            request_options: GrowsurfRuby::RequestOptions::OrHash
+          ).returns(
+            GrowsurfRuby::Models::Campaign::ParticipantBulkDeleteResponse
+          )
+        end
+        def bulk_delete(
+          # GrowSurf program ID.
+          id,
+          # GrowSurf participant IDs and/or email addresses to delete. Mixed entries are
+          # allowed.
+          participants:,
+          request_options: {}
+        )
+        end
+
         # Adds a new participant to the program. If the email already exists, the existing
         # participant is returned.
         sig do
@@ -112,6 +145,10 @@ module GrowsurfRuby
           # for mobile participant creation and mobile participant token flows. The official
           # mobile SDKs generate this as a lowercase UUID.
           mobile_instance_id: nil,
+          # The referral credit status; only meaningful when `referred_by` resolves to a
+          # referrer. When omitted it is derived from the program's referral trigger
+          # (`CREDIT_AWARDED`, `CREDIT_PENDING`, or `CREDIT_EXPIRED`); left unset when no
+          # referrer resolves.
           referral_status: nil,
           # Referrer participant ID or email address.
           referred_by: nil,
@@ -245,6 +282,13 @@ module GrowsurfRuby
 
         # 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.
         sig do
           params(
             participant_id_or_email: String,
@@ -400,6 +444,8 @@ 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
+        # program; the request fails until one is verified.
         sig do
           params(
             participant_id_or_email: String,
@@ -474,6 +520,120 @@ 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 account to be verified by the
+        # GrowSurf team. 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.
+        sig do
+          params(
+            participant_id_or_email: String,
+            id: String,
+            body: String,
+            email_type: String,
+            preheader: String,
+            subject: String,
+            request_options: GrowsurfRuby::RequestOptions::OrHash
+          ).returns(GrowsurfRuby::Models::Campaign::ParticipantEmailResponse)
+        end
+        def email(
+          # Path param: GrowSurf participant ID or URL-encoded participant email address.
+          participant_id_or_email,
+          # Path param: GrowSurf program ID.
+          id:,
+          # Body param: HTML body for a free-form email. You can personalize it with
+          # dynamic text, inserting `{{...}}` tokens like `{{firstName}}` or `{{shareUrl}}`.
+          # See [Guide to using dynamic text in GrowSurf emails](https://support.growsurf.com/article/213-guide-to-using-dynamic-text-in-growsurf-emails).
+          body: nil,
+          # Body param: The program email template to send (template mode). Send the
+          # camelCase key. The valid types depend on the program type; `isEnabled` only
+          # controls automatic sends. Referral programs: `welcomeNonReferred`,
+          # `referralLinkViewedFirstTime`, `referralLinkUsed`, `referredSignup`,
+          # `welcomeReferred`, `goalAchieved`, `campaignEndedWinners`,
+          # `campaignEndedNonWinners`, `progressUpdateMonthly`. Affiliate programs:
+          # `welcomeNonReferred`, `referralLinkViewedFirstTime`, `referredSignup`,
+          # `commissionGenerated`, `commissionAdjusted`, `payoutPending`,
+          # `payoutSentSuccess`, `progressUpdateMonthly`. System/transactional types (login
+          # link, PayPal confirmation, tax) and the invite email cannot be sent.
+          email_type: nil,
+          # Body param: Optional preheader text for a free-form email.
+          preheader: nil,
+          # Body param: Subject line for a free-form email. Supports dynamic text
+          # (`{{...}}` tokens), the same as the body.
+          subject: nil,
+          request_options: {}
+        )
+        end
+
+        # Returns a participant's activity logs, most recent first (offset/limit paginated).
+        sig do
+          params(
+            participant_id_or_email: String,
+            id: String,
+            limit: Integer,
+            offset: Integer,
+            request_options: GrowsurfRuby::RequestOptions::OrHash
+          ).returns(
+            GrowsurfRuby::Models::Campaign::ParticipantActivityLogsResponse
+          )
+        end
+        def list_activity_logs(
+          # Path param: GrowSurf participant ID or URL-encoded participant email address.
+          participant_id_or_email,
+          # Path param: GrowSurf program ID.
+          id:,
+          # Query param: Number of logs to return (1–100, default 20).
+          limit: nil,
+          # Query param: Number of logs to skip.
+          offset: nil,
+          request_options: {}
+        )
+        end
+
+        # 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.
+        sig do
+          params(
+            participant_id_or_email: String,
+            id: String,
+            days: Integer,
+            end_date: Integer,
+            include:
+              GrowsurfRuby::Campaign::ParticipantRetrieveAnalyticsParams::Include::OrSymbol,
+            interval:
+              GrowsurfRuby::Campaign::ParticipantRetrieveAnalyticsParams::Interval::OrSymbol,
+            start_date: Integer,
+            request_options: GrowsurfRuby::RequestOptions::OrHash
+          ).returns(
+            GrowsurfRuby::Models::Campaign::ParticipantAnalyticsResponse
+          )
+        end
+        def retrieve_analytics(
+          # GrowSurf participant ID or URL-encoded participant email address.
+          participant_id_or_email,
+          # GrowSurf program ID.
+          id:,
+          # Last number of days to retrieve analytics for. Defaults to 365. Maximum 1825.
+          days: nil,
+          # End date of the analytics timeframe as a Unix timestamp in milliseconds.
+          # Required if `days` is not set.
+          end_date: nil,
+          # Set to `series` to also return this participant's own activity per period.
+          include: nil,
+          # Bucket size for the `series` (only used with `include=series`). Defaults to `day`.
+          interval: nil,
+          # Start date of the analytics timeframe as a Unix timestamp in milliseconds.
+          # Required if `days` is not set.
+          start_date: nil,
+          request_options: {}
+        )
+        end
+
         # @api private
         sig { params(client: GrowsurfRuby::Client).returns(T.attached_class) }
         def self.new(client:)

data/rbi/growsurf_ruby/resources/campaign/rewards.rbi

@@ -4,7 +4,7 @@ module GrowsurfRuby
   module Resources
     class Campaign
       class Rewards
-        # Retrieves the active, visible, and enabled rewards configured for a program.
+        # Retrieves the rewards configured for a program.
         sig do
           params(
             id: String,
@@ -30,7 +30,6 @@ module GrowsurfRuby
             coupon_code: String,
             description: String,
             image_url: String,
-            is_active: T::Boolean,
             is_unlimited: T::Boolean,
             is_visible: T::Boolean,
             limit: Integer,
@@ -44,7 +43,9 @@ module GrowsurfRuby
             referral_coupon_code: String,
             referral_description: String,
             referred_reward_upfront: T::Boolean,
+            referred_value: GrowsurfRuby::RewardTaxValuation::OrHash,
             title: String,
+            value: GrowsurfRuby::RewardTaxValuation::OrHash,
             request_options: GrowsurfRuby::RequestOptions::OrHash
           ).returns(GrowsurfRuby::Models::Campaign::Reward)
         end
@@ -57,17 +58,20 @@ module GrowsurfRuby
           commission_structure: nil,
           # Body param
           conversions_required: nil,
-          # Body param
+          # Body param: Legacy static coupon code shown to the referrer in the reward-won
+          # email and webhook. Display text only; superseded by a connected billing
+          # integration's issued coupon when one exists.
           coupon_code: nil,
           # Body param
           description: nil,
           # Body param
           image_url: nil,
-          # Body param
-          is_active: nil,
-          # Body param
+          # Body param: Whether the reward can be earned an unlimited number of times.
+          # Defaults to `true`, except `MILESTONE` rewards, which can only be earned once.
           is_unlimited: nil,
-          # Body param
+          # Body param: Whether the reward is enabled. When `false` the reward is disabled:
+          # hidden from participants and no longer awarded, including those who already
+          # earned it.
           is_visible: nil,
           # Body param
           limit: nil,
@@ -76,38 +80,49 @@ module GrowsurfRuby
           # Body param: Custom key/value metadata (single-level; values are stored as
           # strings).
           metadata: nil,
-          # Body param
+          # Body param: Text shown before a participant's referral count in
+          # milestone-progress copy. Applies to `MILESTONE` rewards.
           next_milestone_prefix: nil,
-          # Body param
+          # Body param: Text shown after a participant's referral count in
+          # milestone-progress copy. Applies to `MILESTONE` rewards.
           next_milestone_suffix: nil,
-          # Body param
+          # Body param: The number of winners (`LEADERBOARD` rewards only). With
+          # `limitDuration` `PER_MONTH` this many win each month, otherwise this many win
+          # in total; omitting it defaults to `3`.
           number_of_winners: nil,
           # Body param
           order: nil,
-          # Body param
+          # Body param: Legacy static coupon code shown to the referred friend
+          # (double-sided rewards) in the reward-won email and webhook. Display text only;
+          # superseded by a connected billing integration's issued coupon when one exists.
           referral_coupon_code: nil,
           # Body param
           referral_description: nil,
           # Body param
           referred_reward_upfront: nil,
+          # Body param: Tax valuation for the referred friend's side of a double-sided
+          # reward. Defaults to not tax-reportable (a purchase rebate).
+          referred_value: nil,
           # Body param
           title: nil,
+          # Body param: Tax valuation for the reward (the referrer's side of a
+          # double-sided reward). Used by tax documentation / 1099 reporting.
+          value: nil,
           request_options: {}
         )
         end
 
-        # Updates an existing program reward. Only the fields you send are changed; `type`
+        # Updates an existing campaign reward. Only the fields you send are changed; `type`
         # is immutable and must not be supplied.
         sig do
           params(
-            reward_id: String,
+            campaign_reward_id: String,
             id: String,
             commission_structure: GrowsurfRuby::CommissionStructure::OrHash,
             conversions_required: Integer,
             coupon_code: String,
             description: String,
             image_url: String,
-            is_active: T::Boolean,
             is_unlimited: T::Boolean,
             is_visible: T::Boolean,
             limit: Integer,
@@ -121,30 +136,35 @@ module GrowsurfRuby
             referral_coupon_code: String,
             referral_description: String,
             referred_reward_upfront: T::Boolean,
+            referred_value: GrowsurfRuby::RewardTaxValuation::OrHash,
             title: String,
+            value: GrowsurfRuby::RewardTaxValuation::OrHash,
             request_options: GrowsurfRuby::RequestOptions::OrHash
           ).returns(GrowsurfRuby::Models::Campaign::Reward)
         end
         def update(
-          # Path param: Program reward ID.
-          reward_id,
+          # Path param: Campaign reward ID.
+          campaign_reward_id,
           # Path param: GrowSurf program ID.
           id:,
           # Body param
           commission_structure: nil,
           # Body param
           conversions_required: nil,
-          # Body param
+          # Body param: Legacy static coupon code shown to the referrer in the reward-won
+          # email and webhook. Display text only; superseded by a connected billing
+          # integration's issued coupon when one exists.
           coupon_code: nil,
           # Body param
           description: nil,
           # Body param
           image_url: nil,
-          # Body param
-          is_active: nil,
-          # Body param
+          # Body param: Whether the reward can be earned an unlimited number of times.
+          # Defaults to `true`, except `MILESTONE` rewards, which can only be earned once.
           is_unlimited: nil,
-          # Body param
+          # Body param: Whether the reward is enabled. When `false` the reward is disabled:
+          # hidden from participants and no longer awarded, including those who already
+          # earned it.
           is_visible: nil,
           # Body param
           limit: nil,
@@ -153,37 +173,49 @@ module GrowsurfRuby
           # Body param: Custom key/value metadata (single-level; values are stored as
           # strings).
           metadata: nil,
-          # Body param
+          # Body param: Text shown before a participant's referral count in
+          # milestone-progress copy. Applies to `MILESTONE` rewards.
           next_milestone_prefix: nil,
-          # Body param
+          # Body param: Text shown after a participant's referral count in
+          # milestone-progress copy. Applies to `MILESTONE` rewards.
           next_milestone_suffix: nil,
-          # Body param
+          # Body param: The number of winners (`LEADERBOARD` rewards only). With
+          # `limitDuration` `PER_MONTH` this many win each month, otherwise this many win
+          # in total; omitting it defaults to `3`.
           number_of_winners: nil,
           # Body param
           order: nil,
-          # Body param
+          # Body param: Legacy static coupon code shown to the referred friend
+          # (double-sided rewards) in the reward-won email and webhook. Display text only;
+          # superseded by a connected billing integration's issued coupon when one exists.
           referral_coupon_code: nil,
           # Body param
           referral_description: nil,
           # Body param
           referred_reward_upfront: nil,
+          # Body param: Tax valuation for the referred friend's side of a double-sided
+          # reward. Defaults to not tax-reportable (a purchase rebate).
+          referred_value: nil,
           # Body param
           title: nil,
+          # Body param: Tax valuation for the reward (the referrer's side of a
+          # double-sided reward). Used by tax documentation / 1099 reporting.
+          value: nil,
           request_options: {}
         )
         end
 
-        # Deletes a program reward.
+        # Deletes a campaign reward.
         sig do
           params(
-            reward_id: String,
+            campaign_reward_id: String,
             id: String,
             request_options: GrowsurfRuby::RequestOptions::OrHash
           ).returns(GrowsurfRuby::Models::Campaign::DeleteRewardResponse)
         end
         def delete(
-          # Program reward ID.
-          reward_id,
+          # Campaign reward ID.
+          campaign_reward_id,
           # GrowSurf program ID.
           id:,
           request_options: {}

data/rbi/growsurf_ruby/resources/campaign/webhooks.rbi

@@ -0,0 +1,123 @@
+# typed: strong
+
+module GrowsurfRuby
+  module Resources
+    class Campaign
+      class Webhooks
+        # Lists a program's webhooks (secrets are never returned).
+        sig do
+          params(
+            id: String,
+            request_options: GrowsurfRuby::RequestOptions::OrHash
+          ).returns(GrowsurfRuby::Models::Campaign::WebhookListResponse)
+        end
+        def list(
+          # GrowSurf program ID.
+          id,
+          request_options: {}
+        )
+        end
+
+        # Adds a webhook to the program.
+        sig do
+          params(
+            id: String,
+            payload_url: String,
+            events: T::Array[GrowsurfRuby::Campaign::WebhookEvent::OrSymbol],
+            is_enabled: T::Boolean,
+            secret: String,
+            request_options: GrowsurfRuby::RequestOptions::OrHash
+          ).returns(GrowsurfRuby::Models::Campaign::Webhook)
+        end
+        def create(
+          # Path param: GrowSurf program ID.
+          id,
+          # Body param: The URL that receives webhook deliveries.
+          payload_url:,
+          # Body param: The events this webhook is subscribed to. When omitted, it is
+          # subscribed to no events.
+          events: nil,
+          # Body param
+          is_enabled: nil,
+          # Body param: Write-only. Used to sign deliveries (the `GrowSurf-Signature` HMAC
+          # header). Never returned.
+          secret: nil,
+          request_options: {}
+        )
+        end
+
+        # Updates a webhook by id.
+        sig do
+          params(
+            webhook_id: String,
+            id: String,
+            events: T::Array[GrowsurfRuby::Campaign::WebhookEvent::OrSymbol],
+            is_enabled: T::Boolean,
+            payload_url: String,
+            secret: String,
+            request_options: GrowsurfRuby::RequestOptions::OrHash
+          ).returns(GrowsurfRuby::Models::Campaign::Webhook)
+        end
+        def update(
+          # Path param: The webhook id (`primary` for the program's primary webhook).
+          webhook_id,
+          # Path param: GrowSurf program ID.
+          id:,
+          # Body param
+          events: nil,
+          # Body param
+          is_enabled: nil,
+          # Body param
+          payload_url: nil,
+          # Body param: Write-only.
+          secret: nil,
+          request_options: {}
+        )
+        end
+
+        # Removes a webhook by id.
+        sig do
+          params(
+            webhook_id: String,
+            id: String,
+            request_options: GrowsurfRuby::RequestOptions::OrHash
+          ).returns(GrowsurfRuby::Models::Campaign::WebhookDeleteResponse)
+        end
+        def delete(
+          # The webhook id (`primary` for the program's primary webhook).
+          webhook_id,
+          # GrowSurf program ID.
+          id:,
+          request_options: {}
+        )
+        end
+
+        # Sends a live test event to a webhook using its stored URL and secret.
+        sig do
+          params(
+            webhook_id: String,
+            id: String,
+            event: GrowsurfRuby::Campaign::WebhookEvent::OrSymbol,
+            request_options: GrowsurfRuby::RequestOptions::OrHash
+          ).returns(GrowsurfRuby::Models::Campaign::WebhookTestResponse)
+        end
+        def test(
+          # Path param: The webhook id (`primary` for the program's primary webhook).
+          webhook_id,
+          # Path param: GrowSurf program ID.
+          id:,
+          # Body param: The event to simulate. When omitted, the webhook's first enabled
+          # event is used (returns `400` if it has no enabled events).
+          event: nil,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: GrowsurfRuby::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end