growsurf-ruby 1.0.0 → 1.1.0

data/rbi/growsurf_ruby/models/campaign_update_params.rbi

@@ -91,16 +91,6 @@ module GrowsurfRuby
           end
         OrSymbol = T.type_alias { T.any(Symbol, String) }
 
-        DRAFT =
-          T.let(
-            :DRAFT,
-            GrowsurfRuby::CampaignUpdateParams::Status::TaggedSymbol
-          )
-        PENDING =
-          T.let(
-            :PENDING,
-            GrowsurfRuby::CampaignUpdateParams::Status::TaggedSymbol
-          )
         IN_PROGRESS =
           T.let(
             :IN_PROGRESS,
@@ -111,11 +101,6 @@ module GrowsurfRuby
             :COMPLETE,
             GrowsurfRuby::CampaignUpdateParams::Status::TaggedSymbol
           )
-        CANCELLED =
-          T.let(
-            :CANCELLED,
-            GrowsurfRuby::CampaignUpdateParams::Status::TaggedSymbol
-          )
 
         sig do
           override.returns(

data/rbi/growsurf_ruby/models/commission_structure.rbi

@@ -14,6 +14,9 @@ module GrowsurfRuby
       sig { returns(T.nilable(Integer)) }
       attr_accessor :amount
 
+      sig { returns(T.nilable(String)) }
+      attr_accessor :amount_iso
+
       sig { returns(T.nilable(T::Boolean)) }
       attr_accessor :approval_required
 
@@ -75,6 +78,7 @@ module GrowsurfRuby
       sig do
         params(
           amount: T.nilable(Integer),
+          amount_iso: T.nilable(String),
           approval_required: T.nilable(T::Boolean),
           duration: T.nilable(String),
           duration_in_months: T.nilable(Integer),
@@ -97,6 +101,7 @@ module GrowsurfRuby
       end
       def self.new(
         amount: nil,
+        amount_iso: nil,
         approval_required: nil,
         duration: nil,
         duration_in_months: nil,
@@ -122,6 +127,7 @@ module GrowsurfRuby
         override.returns(
           {
             amount: T.nilable(Integer),
+            amount_iso: T.nilable(String),
             approval_required: T.nilable(T::Boolean),
             duration: T.nilable(String),
             duration_in_months: T.nilable(Integer),
@@ -158,8 +164,8 @@ module GrowsurfRuby
 
         PERCENT =
           T.let(:PERCENT, GrowsurfRuby::CommissionStructure::Type::TaggedSymbol)
-        AMOUNT =
-          T.let(:AMOUNT, GrowsurfRuby::CommissionStructure::Type::TaggedSymbol)
+        FIXED =
+          T.let(:FIXED, GrowsurfRuby::CommissionStructure::Type::TaggedSymbol)
 
         sig do
           override.returns(

data/rbi/growsurf_ruby/models/referral_flow_screenshots_response.rbi

@@ -0,0 +1,94 @@
+# typed: strong
+
+module GrowsurfRuby
+  module Models
+    class ReferralFlowScreenshotsResponse < GrowsurfRuby::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            GrowsurfRuby::Models::ReferralFlowScreenshotsResponse,
+            GrowsurfRuby::Internal::AnyHash
+          )
+        end
+
+      sig { returns(GrowsurfRuby::Models::ReferralFlowScreenshotsResponse::ReferralFlowScreenshot) }
+      attr_reader :referrer
+
+      sig do
+        params(
+          referrer: GrowsurfRuby::Models::ReferralFlowScreenshotsResponse::ReferralFlowScreenshot::OrHash
+        ).void
+      end
+      attr_writer :referrer
+
+      sig { returns(GrowsurfRuby::Models::ReferralFlowScreenshotsResponse::ReferralFlowScreenshot) }
+      attr_reader :referred_friend
+
+      sig do
+        params(
+          referred_friend: GrowsurfRuby::Models::ReferralFlowScreenshotsResponse::ReferralFlowScreenshot::OrHash
+        ).void
+      end
+      attr_writer :referred_friend
+
+      sig { returns(Integer) }
+      attr_accessor :generated_at
+
+      sig do
+        params(
+          referrer: GrowsurfRuby::Models::ReferralFlowScreenshotsResponse::ReferralFlowScreenshot::OrHash,
+          referred_friend: GrowsurfRuby::Models::ReferralFlowScreenshotsResponse::ReferralFlowScreenshot::OrHash,
+          generated_at: Integer
+        ).returns(T.attached_class)
+      end
+      def self.new(referrer:, referred_friend:, generated_at:)
+      end
+
+      sig do
+        override.returns(
+          {
+            referrer: GrowsurfRuby::Models::ReferralFlowScreenshotsResponse::ReferralFlowScreenshot,
+            referred_friend: GrowsurfRuby::Models::ReferralFlowScreenshotsResponse::ReferralFlowScreenshot,
+            generated_at: Integer
+          }
+        )
+      end
+      def to_hash
+      end
+
+      class ReferralFlowScreenshot < GrowsurfRuby::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              GrowsurfRuby::Models::ReferralFlowScreenshotsResponse::ReferralFlowScreenshot,
+              GrowsurfRuby::Internal::AnyHash
+            )
+          end
+
+        sig { returns(String) }
+        attr_accessor :view
+
+        sig { returns(String) }
+        attr_accessor :url
+
+        sig { returns(Integer) }
+        attr_accessor :width
+
+        sig { returns(Integer) }
+        attr_accessor :height
+
+        sig do
+          params(view: String, url: String, width: Integer, height: Integer).returns(T.attached_class)
+        end
+        def self.new(view:, url:, width:, height:)
+        end
+
+        sig do
+          override.returns({view: String, url: String, width: Integer, height: Integer})
+        end
+        def to_hash
+        end
+      end
+    end
+  end
+end

data/rbi/growsurf_ruby/models.rbi

@@ -1,6 +1,12 @@
 # typed: strong
 
 module GrowsurfRuby
+  Account = GrowsurfRuby::Models::Account
+
+  AccountCreateParams = GrowsurfRuby::Models::AccountCreateParams
+
+  AccountUpdateParams = GrowsurfRuby::Models::AccountUpdateParams
+
   Campaign = GrowsurfRuby::Models::Campaign
 
   CampaignAPI = GrowsurfRuby::Models::CampaignAPI
@@ -43,5 +49,8 @@ module GrowsurfRuby
 
   ReferralList = GrowsurfRuby::Models::ReferralList
 
+  ReferralFlowScreenshotsResponse =
+    GrowsurfRuby::Models::ReferralFlowScreenshotsResponse
+
   RewardTaxValuation = GrowsurfRuby::Models::RewardTaxValuation
 end

data/rbi/growsurf_ruby/resources/account.rbi

@@ -0,0 +1,112 @@
+# typed: strong
+
+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, but the key is
+      # locked until the account's email address is verified: authenticated endpoints
+      # outside the `Accounts` group return a `403` with error code
+      # `EMAIL_NOT_VERIFIED_ERROR` until then (resend the email via `POST
+      # /account/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 the GrowSurf team to verify the account
+      # 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).
+      sig do
+        params(
+          email: String,
+          company: String,
+          first_name: String,
+          last_name: String,
+          request_options: GrowsurfRuby::RequestOptions::OrHash
+        ).returns(GrowsurfRuby::Models::AccountCreateResponse)
+      end
+      def create(
+        # The email address for the new account. Personal emails and disposable email addresses are not accepted.
+        email:,
+        company: nil,
+        first_name: nil,
+        last_name: nil,
+        request_options: {}
+      )
+      end
+
+      # Retrieves the account that owns the API key: profile and GrowSurf-team
+      # verification state.
+      # `verificationStatus` is `VERIFIED` once the GrowSurf team has verified the account
+      # — this is required before you can send participant emails from a program.
+      sig do
+        params(request_options: GrowsurfRuby::RequestOptions::OrHash).returns(
+          GrowsurfRuby::Account
+        )
+      end
+      def retrieve(request_options: {})
+      end
+
+      # Updates your own account profile (`firstName`, `lastName`, `company`). Any other
+      # property is rejected with a `400` — in particular, the account `email` cannot be
+      # changed via the API, and billing/subscription is not editable here.
+      sig do
+        params(
+          company: String,
+          first_name: String,
+          last_name: String,
+          request_options: GrowsurfRuby::RequestOptions::OrHash
+        ).returns(GrowsurfRuby::Account)
+      end
+      def update(
+        company: nil,
+        first_name: nil,
+        last_name: nil,
+        request_options: {}
+      )
+      end
+
+      # Generates a new API key and immediately revokes the old one. The key used to make
+      # this request stops working as soon as the response is returned — update every
+      # integration that used the old key with the new one. The account owner is
+      # notified by email whenever the key is rotated.
+      sig do
+        params(request_options: GrowsurfRuby::RequestOptions::OrHash).returns(
+          GrowsurfRuby::Models::AccountRotateAPIKeyResponse
+        )
+      end
+      def rotate_api_key(request_options: {})
+      end
+
+      # Requests GrowSurf-team verification of your account (required before a program can
+      # email its participants). Idempotent — calling it again while a request is pending
+      # does not create a duplicate. Returns the account with its updated
+      # `verificationStatus`.
+      sig do
+        params(request_options: GrowsurfRuby::RequestOptions::OrHash).returns(
+          GrowsurfRuby::Account
+        )
+      end
+      def request_verification(request_options: {})
+      end
+
+      # Resends the email-verification email to the account's email address. A `200`
+      # with `status: SENT` is only returned when an email was actually dispatched.
+      # Returns a `400` if the email is already verified, or a `429` if a verification
+      # email was sent too recently — wait a moment, then retry.
+      sig do
+        params(request_options: GrowsurfRuby::RequestOptions::OrHash).returns(
+          GrowsurfRuby::Models::AccountResendVerificationEmailResponse
+        )
+      end
+      def resend_verification_email(request_options: {})
+      end
+
+      # @api private
+      sig { params(client: GrowsurfRuby::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/growsurf_ruby/resources/campaign/design.rbi

@@ -6,8 +6,8 @@ module GrowsurfRuby
       class Design
         # Retrieves a program's design configuration — the same surface as the dashboard
         # Program Editor's **Design** tab. This is a large, deeply nested object whose
-        # available fields depend on the program type. See the API reference for the full
-        # field list.
+        # available fields depend on the program type; the response includes every field
+        # and its current value, which is the same shape you send back on update.
         sig do
           params(
             id: String,
@@ -21,9 +21,11 @@ module GrowsurfRuby
         )
         end
 
-        # Updates a program's design configuration. Only the fields you send are changed.
-        # The request body is a partial design object — see the API reference for the full
-        # field list.
+        # Updates a program's design configuration. Only the fields you send are changed;
+        # anything you leave out is untouched (arrays such as `signup.fields` replace
+        # wholesale). The request body is a partial design 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.
         sig do
           params(
             id: String,

data/rbi/growsurf_ruby/resources/campaign/emails.rbi

@@ -5,8 +5,9 @@ module GrowsurfRuby
     class Campaign
       class Emails
         # Retrieves a program's email configuration — the same surface as the dashboard
-        # Program Editor's **Emails** tab. This is a large, nested object. See the API
-        # reference for the full field list.
+        # Program Editor's **Emails** tab. 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.
         sig do
           params(
             id: String,
@@ -20,9 +21,10 @@ module GrowsurfRuby
         )
         end
 
-        # Updates a program's email configuration. Only the fields you send are changed.
-        # The request body is a partial email configuration object — see the API reference
-        # for the full field list.
+        # Updates a program's email configuration. Only the fields you send are changed;
+        # anything you leave out is untouched. The request body is a partial email
+        # configuration 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.
         sig do
           params(
             id: String,

data/rbi/growsurf_ruby/resources/campaign/installation.rbi

@@ -6,8 +6,9 @@ module GrowsurfRuby
       class Installation
         # Retrieves a program's installation configuration — the same surface as the
         # dashboard Program Editor's **Installation** tab. This is a nested object whose
-        # available fields depend on the program type. See the API reference for the full
-        # field list.
+        # available fields depend on the program type. 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.
         sig do
           params(
             id: String,
@@ -22,8 +23,10 @@ module GrowsurfRuby
         end
 
         # Updates a program's installation configuration. Only the fields you send are
-        # changed. The request body is a partial installation configuration object — see
-        # the API reference for the full field list.
+        # changed; anything you leave out is untouched. The request body is a partial
+        # installation configuration 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.
         sig do
           params(
             id: String,

data/rbi/growsurf_ruby/resources/campaign/options.rbi

@@ -5,8 +5,9 @@ module GrowsurfRuby
     class Campaign
       class Options
         # Retrieves a program's options configuration — the same surface as the dashboard
-        # Program Editor's **Options** tab. This is a large, nested object. See the API
-        # reference for the full field list.
+        # Program Editor's **Options** tab. 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.
         sig do
           params(
             id: String,
@@ -20,9 +21,10 @@ module GrowsurfRuby
         )
         end
 
-        # Updates a program's options configuration. Only the fields you send are changed.
-        # The request body is a partial options configuration object — see the API
-        # reference for the full field list.
+        # Updates a program's options configuration. Only the fields you send are changed;
+        # anything you leave out is untouched. The request body is a partial options
+        # configuration 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.
         sig do
           params(
             id: String,

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:)