growsurf-ruby 1.2.0 → 1.3.0

data/rbi/growsurf_ruby/resources/campaign.rbi

@@ -61,10 +61,8 @@ module GrowsurfRuby
       def list(request_options: {})
       end
 
-      # Creates a program. Only `type` is required; everything else is server-defaulted.
-      # The new program is owned by the API key's bound team. Editor-tab configuration
-      # (design, emails, options, installation) is not accepted here — configure it via
-      # the config sub-resources after the program is created.
+      # Creates a new program, plus any optional campaign rewards. The new program is
+      # created in `DRAFT` status and owned by the API key's bound team.
       sig do
         params(
           type: GrowsurfRuby::CampaignCreateParams::Type::OrSymbol,
@@ -84,7 +82,7 @@ module GrowsurfRuby
         # ISO 4217 currency code. Defaults to USD. Chosen when the program is created and
         # immutable afterward — it cannot be changed on update.
         currency_iso: nil,
-        # The program name. Defaults to "Untitled Program".
+        # The program name. Defaults to a generated friendly label plus the creation date.
         name: nil,
         # Optional inline rewards to create with the program.
         rewards: nil,
@@ -92,10 +90,11 @@ module GrowsurfRuby
       )
       end
 
-      # Updates a program's identity and lifecycle. Only the fields you send are changed.
-      # `type`, `urlId`, and `currencyISO` are immutable. Editor-tab configuration (design, emails,
-      # options, installation) is edited via the dedicated config sub-resources, not
-      # here.
+      # Updates a program's identity and lifecycle. Only the fields you send are
+      # changed. `type`, `urlId`, and `currencyISO` are immutable. Editor-tab
+      # configuration (design, emails, options, installation) is edited via the
+      # dedicated config sub-resources, not here. The program cannot be deleted via this
+      # endpoint.
       sig do
         params(
           id: String,
@@ -122,7 +121,8 @@ module GrowsurfRuby
       )
       end
 
-      # Clones an existing program, returning the newly created program.
+      # Clones an existing program into a new `DRAFT` program. Integrations and
+      # credentials are not copied; active rewards are cloned.
       sig do
         params(
           id: String,
@@ -136,6 +136,31 @@ module GrowsurfRuby
       )
       end
 
+      # Invites someone to join the affiliate program. GrowSurf emails them a single-use
+      # accept link; accepting it enrolls them as an approved affiliate without going
+      # through the public application. One active invite can exist per email address.
+      sig do
+        params(
+          id: String,
+          email: String,
+          first_name: String,
+          last_name: String,
+          request_options: GrowsurfRuby::RequestOptions::OrHash
+        ).returns(GrowsurfRuby::AffiliateInvite)
+      end
+      def create_affiliate_invite(
+        # GrowSurf program ID.
+        id,
+        # Valid email address to invite. Maximum 255 characters.
+        email:,
+        # Invitee first name, used in the invite email. Maximum 255 characters.
+        first_name: nil,
+        # Invitee last name. Maximum 255 characters.
+        last_name: nil,
+        request_options: {}
+      )
+      end
+
       # Creates or returns a participant using the same input behavior as Add
       # Participant, then returns a participant-scoped token for GrowSurf mobile SDK
       # participant endpoints. Use this endpoint from your backend after your mobile app
@@ -179,7 +204,59 @@ module GrowsurfRuby
       )
       end
 
-      # Retrieves a paged list of all participant commissions in an affiliate program.
+      # Lists an affiliate program's applications, newest first. Applications exist on
+      # programs that review public signups (an `affiliateApplicationMode` of
+      # `MANUAL_REVIEW` or `AUTO_APPROVE`). A pending applicant is not a participant
+      # until their application is approved.
+      sig do
+        params(
+          id: String,
+          limit: Integer,
+          offset: Integer,
+          status:
+            GrowsurfRuby::CampaignListAffiliateApplicationsParams::Status::OrSymbol,
+          request_options: GrowsurfRuby::RequestOptions::OrHash
+        ).returns(GrowsurfRuby::Models::AffiliateApplicationListResponse)
+      end
+      def list_affiliate_applications(
+        # GrowSurf program ID.
+        id,
+        # How many applications to return per page (1-100).
+        limit: nil,
+        # Offset number used to skip through a result set.
+        offset: nil,
+        # Only return applications with this status.
+        status: nil,
+        request_options: {}
+      )
+      end
+
+      # Lists an affiliate program's enrollment invites, newest first.
+      sig do
+        params(
+          id: String,
+          limit: Integer,
+          offset: Integer,
+          status:
+            GrowsurfRuby::CampaignListAffiliateInvitesParams::Status::OrSymbol,
+          request_options: GrowsurfRuby::RequestOptions::OrHash
+        ).returns(GrowsurfRuby::Models::AffiliateInviteListResponse)
+      end
+      def list_affiliate_invites(
+        # GrowSurf program ID.
+        id,
+        # How many invites to return per page (1-100).
+        limit: nil,
+        # Offset number used to skip through a result set.
+        offset: nil,
+        # Only return invites with this status.
+        status: nil,
+        request_options: {}
+      )
+      end
+
+      # **Affiliate programs only.** Retrieves a paged list of all participant
+      # commissions in an affiliate program.
       sig do
         params(
           id: String,
@@ -249,7 +326,8 @@ module GrowsurfRuby
       )
       end
 
-      # Retrieves a paged list of all participant payouts in an affiliate program.
+      # **Affiliate programs only.** Retrieves a paged list of all participant payouts
+      # in an affiliate program.
       sig do
         params(
           id: String,
@@ -313,7 +391,47 @@ module GrowsurfRuby
       )
       end
 
-      # Retrieves analytics for a program.
+      # Re-sends a pending invite with a fresh accept link (the previous link stops working).
+      # Resends are rate limited per invite; retry after a few minutes if a resend was just sent.
+      sig do
+        params(
+          invite_id: String,
+          id: String,
+          request_options: GrowsurfRuby::RequestOptions::OrHash
+        ).returns(GrowsurfRuby::AffiliateInvite)
+      end
+      def resend_affiliate_invite(
+        # Affiliate invite ID.
+        invite_id,
+        # GrowSurf program ID.
+        id:,
+        request_options: {}
+      )
+      end
+
+      # Returns one affiliate application, including its submitted form answers.
+      sig do
+        params(
+          application_id: String,
+          id: String,
+          request_options: GrowsurfRuby::RequestOptions::OrHash
+        ).returns(GrowsurfRuby::AffiliateApplication)
+      end
+      def retrieve_affiliate_application(
+        # Affiliate application ID.
+        application_id,
+        # GrowSurf program ID.
+        id:,
+        request_options: {}
+      )
+      end
+
+      # Retrieves analytics for a program. Pass `interval` to also get a time-series (`series`)
+      # alongside the totals, and `include` to add previous-period totals, status breakdowns,
+      # derived rates, or email performance. Add `email` to `include` for `sent` (accepted for
+      # delivery), `delivered`, `opened`, `clicked`, `bounced`, and `spamComplaints` metrics plus
+      # per-email-type breakdowns. Email rates are ratios from `0` to `1`, and `isPartial`
+      # identifies windows that begin before complete coverage.
       sig do
         params(
           id: String,
@@ -334,11 +452,14 @@ module GrowsurfRuby
         # End date of the analytics timeframe as a Unix timestamp in milliseconds.
         # Required if `days` is not set.
         end_date: nil,
-        # Comma-separated list of optional enrichments (opt-in to keep the default response
-        # lean): `previousPeriod` adds totals for the equal-length window immediately before
-        # the requested one; `statusCounts` adds reward (and, for affiliate programs,
-        # affiliate/commission/payout) status breakdowns; `rates` adds derived referral
-        # rates.
+        # Comma-separated list of optional data to include: `previousPeriod` adds totals for the
+        # equal-length window immediately before the requested one; `statusCounts` adds reward
+        # (and, for affiliate programs, affiliate/commission/payout) status breakdowns; `rates`
+        # adds derived referral rates; `email` adds `sent`, `delivered`, `opened`, `clicked`,
+        # `bounced`, `spamComplaints`, and per-email-type metrics. When `email` and an interval
+        # are both requested, each `series` item also contains counts for emails sent during that
+        # period. Combine `email` with `previousPeriod` to include the same email metrics in both
+        # windows.
         include: nil,
         # When set to `day`, `week`, or `month`, the response also includes a `series` array
         # with per-period totals. Defaults to `total` (no series).
@@ -350,6 +471,67 @@ module GrowsurfRuby
       )
       end
 
+      # Decides a pending application. Set `status` to `APPROVED` to enroll the applicant
+      # (this creates the participant, or upgrades an existing participant with the same
+      # email), or to `DENIED` with an optional `rejectionReason`. A denied applicant may
+      # reapply after the program's reapplication cooldown; send an earlier
+      # `reapplyAllowedAt` (without `status`) to shorten that wait for one applicant.
+      # Provide exactly one of `status` or `reapplyAllowedAt`. Denial-only fields are
+      # only valid with `status` set to `DENIED`. Approval is idempotent: repeating it
+      # returns the same participant.
+      sig do
+        params(
+          application_id: String,
+          id: String,
+          allow_immediate_reapply: T::Boolean,
+          reapply_allowed_at: Integer,
+          rejection_reason: String,
+          review_note: String,
+          status:
+            GrowsurfRuby::CampaignReviewAffiliateApplicationParams::Status::OrSymbol,
+          request_options: GrowsurfRuby::RequestOptions::OrHash
+        ).returns(GrowsurfRuby::AffiliateApplication)
+      end
+      def review_affiliate_application(
+        # Affiliate application ID.
+        application_id,
+        # GrowSurf program ID.
+        id:,
+        # Only valid when `status` is `DENIED`; let the applicant reapply right away.
+        allow_immediate_reapply: nil,
+        # For an already-denied application, move the reapplication window to this earlier
+        # time, in Unix milliseconds. Send without `status`.
+        reapply_allowed_at: nil,
+        # Short reason recorded with a denial. Only valid when `status` is `DENIED`.
+        # Maximum 255 characters.
+        rejection_reason: nil,
+        # Private note recorded with a denial. Only valid when `status` is `DENIED`; never
+        # shown to the applicant. Maximum 500 characters.
+        review_note: nil,
+        # The decision. `APPROVED` enrolls the applicant as an affiliate; `DENIED` closes
+        # the application.
+        status: nil,
+        request_options: {}
+      )
+      end
+
+      # Revokes a pending invite. Its emailed accept link stops working immediately.
+      sig do
+        params(
+          invite_id: String,
+          id: String,
+          request_options: GrowsurfRuby::RequestOptions::OrHash
+        ).returns(GrowsurfRuby::AffiliateInvite)
+      end
+      def revoke_affiliate_invite(
+        # Affiliate invite ID.
+        invite_id,
+        # GrowSurf program ID.
+        id:,
+        request_options: {}
+      )
+      end
+
       # @api private
       sig { params(client: GrowsurfRuby::Client).returns(T.attached_class) }
       def self.new(client:)

data/rbi/growsurf_ruby/resources/team.rbi

@@ -3,6 +3,9 @@
 module GrowsurfRuby
   module Resources
     class Team
+      # Retrieves the team bound to the API key or OAuth connection.
+      # `verificationStatus` is `VERIFIED` once GrowSurf has verified the team, which is
+      # required before a program can send participant emails.
       sig do
         params(request_options: GrowsurfRuby::RequestOptions::OrHash).returns(
           GrowsurfRuby::Models::Team
@@ -11,6 +14,9 @@ module GrowsurfRuby
       def retrieve(request_options: {})
       end
 
+      # Updates the name of the team bound to the API key or OAuth connection. Any other
+      # property is rejected with a `400`. Personal profiles, billing, and team
+      # ownership are not editable here.
       sig do
         params(
           name: String,
@@ -20,6 +26,15 @@ module GrowsurfRuby
       def update(name:, request_options: {})
       end
 
+      # Generates a new API key and makes the key used on this request stop working when
+      # rotation succeeds. Send a unique, random `Idempotency-Key`. If the response is
+      # interrupted, immediately retry with the original API key and the same
+      # `Idempotency-Key` to receive the same new key. Update every integration that
+      # used the old key. The team owner is notified by email whenever the key is
+      # rotated. GrowSurf SDKs generate the idempotency key automatically. This endpoint
+      # accepts an API key with `api_key:rotate`. If this scope is unavailable, rotate
+      # the key in the authenticated dashboard instead. This operation is available only
+      # through the REST API or a GrowSurf API SDK, not through MCP.
       sig do
         params(request_options: GrowsurfRuby::RequestOptions::OrHash).returns(
           GrowsurfRuby::Models::TeamRotateAPIKeyResponse
@@ -28,6 +43,9 @@ module GrowsurfRuby
       def rotate_api_key(request_options: {})
       end
 
+      # Requests GrowSurf to verify the bound team (required before a program can email
+      # its participants). Idempotent — calling it again while a request is pending does
+      # not create a duplicate. Returns the team with its updated `verificationStatus`.
       sig do
         params(request_options: GrowsurfRuby::RequestOptions::OrHash).returns(
           GrowsurfRuby::Models::Team
@@ -36,6 +54,11 @@ module GrowsurfRuby
       def request_verification(request_options: {})
       end
 
+      # Resends the email-verification message to the bound team's owner. The response
+      # never reveals the owner's email address. A `200` with `status: SENT` is returned
+      # only when an email was actually dispatched. Returns `400` if the email is
+      # already verified, and `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::TeamResendOwnerVerificationEmailResponse

data/sig/growsurf_ruby/models/affiliate_application.rbs

@@ -0,0 +1,192 @@
+module GrowsurfRuby
+  module Models
+    type affiliate_application =
+      {
+        answers: ::Array[GrowsurfRuby::AffiliateApplication::Answer],
+        created_at: Integer,
+        decided_at: Integer?,
+        email: String?,
+        first_name: String?,
+        id: String,
+        last_name: String?,
+        participant_id: String?,
+        reapply_allowed_at: Integer?,
+        rejection_reason: String?,
+        reviewed_at: Integer?,
+        risk_level: GrowsurfRuby::Models::AffiliateApplication::risk_level?,
+        status: GrowsurfRuby::Models::AffiliateApplication::status,
+        terms_accepted_at: Integer?
+      }
+
+    class AffiliateApplication < GrowsurfRuby::Internal::Type::BaseModel
+      attr_reader answers: ::Array[GrowsurfRuby::AffiliateApplication::Answer]
+
+      def answers=: (
+        ::Array[GrowsurfRuby::AffiliateApplication::Answer]
+      ) -> ::Array[GrowsurfRuby::AffiliateApplication::Answer]
+
+      attr_reader created_at: Integer
+
+      def created_at=: (Integer) -> Integer
+
+      attr_accessor decided_at: Integer?
+
+      attr_accessor email: String?
+
+      attr_accessor first_name: String?
+
+      attr_reader id: String
+
+      def id=: (String) -> String
+
+      attr_accessor last_name: String?
+
+      attr_accessor participant_id: String?
+
+      attr_accessor reapply_allowed_at: Integer?
+
+      attr_accessor rejection_reason: String?
+
+      attr_accessor reviewed_at: Integer?
+
+      attr_accessor risk_level: GrowsurfRuby::Models::AffiliateApplication::risk_level?
+
+      attr_reader status: GrowsurfRuby::Models::AffiliateApplication::status
+
+      def status=: (
+        GrowsurfRuby::Models::AffiliateApplication::status
+      ) -> GrowsurfRuby::Models::AffiliateApplication::status
+
+      attr_reader terms_accepted_at: Integer?
+
+      def terms_accepted_at=: (Integer?) -> Integer?
+
+      def initialize: (
+        answers: ::Array[GrowsurfRuby::AffiliateApplication::Answer],
+        created_at: Integer,
+        decided_at: Integer?,
+        email: String?,
+        first_name: String?,
+        id: String,
+        last_name: String?,
+        participant_id: String?,
+        reapply_allowed_at: Integer?,
+        rejection_reason: String?,
+        reviewed_at: Integer?,
+        risk_level: GrowsurfRuby::Models::AffiliateApplication::risk_level?,
+        status: GrowsurfRuby::Models::AffiliateApplication::status,
+        terms_accepted_at: Integer?
+      ) -> void
+
+      def to_hash: -> {
+        answers: ::Array[GrowsurfRuby::AffiliateApplication::Answer],
+        created_at: Integer,
+        decided_at: Integer?,
+        email: String?,
+        first_name: String?,
+        id: String,
+        last_name: String?,
+        participant_id: String?,
+        reapply_allowed_at: Integer?,
+        rejection_reason: String?,
+        reviewed_at: Integer?,
+        risk_level: GrowsurfRuby::Models::AffiliateApplication::risk_level?,
+        status: GrowsurfRuby::Models::AffiliateApplication::status,
+        terms_accepted_at: Integer?
+      }
+
+      type answer =
+        {
+          field_id: String,
+          label: String,
+          type: GrowsurfRuby::Models::AffiliateApplication::answer_type,
+          value: String | Integer | Float | bool
+        }
+
+      class Answer < GrowsurfRuby::Internal::Type::BaseModel
+        attr_reader field_id: String
+
+        def field_id=: (String) -> String
+
+        attr_reader label: String
+
+        def label=: (String) -> String
+
+        attr_reader type: GrowsurfRuby::Models::AffiliateApplication::answer_type
+
+        def type=: (
+          GrowsurfRuby::Models::AffiliateApplication::answer_type
+        ) -> GrowsurfRuby::Models::AffiliateApplication::answer_type
+
+        attr_reader value: String | Integer | Float | bool
+
+        def value=: (
+          String | Integer | Float | bool
+        ) -> (String | Integer | Float | bool)
+
+        def initialize: (
+          field_id: String,
+          label: String,
+          type: GrowsurfRuby::Models::AffiliateApplication::answer_type,
+          value: String | Integer | Float | bool
+        ) -> void
+
+        def to_hash: -> {
+          field_id: String,
+          label: String,
+          type: GrowsurfRuby::Models::AffiliateApplication::answer_type,
+          value: String | Integer | Float | bool
+        }
+
+        module Type
+          extend GrowsurfRuby::Internal::Type::Enum
+
+          TEXT: :text
+          TEXTAREA: :textarea
+          URL: :url
+          COUNTRY: :country
+          NUMBER: :number
+          DROPDOWN: :dropdown
+          RADIO: :radio
+          CHECKBOX: :checkbox
+
+          def self?.values: -> ::Array[GrowsurfRuby::Models::AffiliateApplication::answer_type]
+        end
+      end
+
+      type answer_type =
+        :text
+        | :textarea
+        | :url
+        | :country
+        | :number
+        | :dropdown
+        | :radio
+        | :checkbox
+
+      type risk_level = :LOW | :MEDIUM | :HIGH
+
+      module RiskLevel
+        extend GrowsurfRuby::Internal::Type::Enum
+
+        LOW: :LOW
+        MEDIUM: :MEDIUM
+        HIGH: :HIGH
+
+        def self?.values: -> ::Array[GrowsurfRuby::Models::AffiliateApplication::risk_level]
+      end
+
+      type status = :PENDING | :APPROVED | :DENIED
+
+      module Status
+        extend GrowsurfRuby::Internal::Type::Enum
+
+        PENDING: :PENDING
+        APPROVED: :APPROVED
+        DENIED: :DENIED
+
+        def self?.values: -> ::Array[GrowsurfRuby::Models::AffiliateApplication::status]
+      end
+    end
+  end
+end

data/sig/growsurf_ruby/models/affiliate_application_list_response.rbs

@@ -0,0 +1,39 @@
+module GrowsurfRuby
+  module Models
+    type affiliate_application_list_response =
+      {
+        applications: ::Array[GrowsurfRuby::AffiliateApplication],
+        total: Integer,
+        limit: Integer,
+        offset: Integer
+      }
+
+    class AffiliateApplicationListResponse < GrowsurfRuby::Internal::Type::BaseModel
+      attr_accessor applications: ::Array[GrowsurfRuby::AffiliateApplication]
+
+      attr_accessor total: Integer
+
+      attr_reader limit: Integer?
+
+      def limit=: (Integer) -> Integer
+
+      attr_reader offset: Integer?
+
+      def offset=: (Integer) -> Integer
+
+      def initialize: (
+        applications: ::Array[GrowsurfRuby::AffiliateApplication],
+        total: Integer,
+        ?limit: Integer,
+        ?offset: Integer
+      ) -> void
+
+      def to_hash: -> {
+        applications: ::Array[GrowsurfRuby::AffiliateApplication],
+        total: Integer,
+        limit: Integer,
+        offset: Integer
+      }
+    end
+  end
+end

data/sig/growsurf_ruby/models/affiliate_invite.rbs

@@ -0,0 +1,92 @@
+module GrowsurfRuby
+  module Models
+    type affiliate_invite =
+      {
+        accepted_at: Integer?,
+        created_at: Integer,
+        email: String,
+        expires_at: Integer,
+        first_name: String?,
+        id: String,
+        last_name: String?,
+        last_sent_at: Integer,
+        revoked_at: Integer?,
+        status: GrowsurfRuby::Models::AffiliateInvite::status
+      }
+
+    class AffiliateInvite < GrowsurfRuby::Internal::Type::BaseModel
+      attr_accessor accepted_at: Integer?
+
+      attr_reader created_at: Integer?
+
+      def created_at=: (Integer) -> Integer
+
+      attr_reader email: String?
+
+      def email=: (String) -> String
+
+      attr_reader expires_at: Integer?
+
+      def expires_at=: (Integer) -> Integer
+
+      attr_accessor first_name: String?
+
+      attr_reader id: String?
+
+      def id=: (String) -> String
+
+      attr_accessor last_name: String?
+
+      attr_reader last_sent_at: Integer?
+
+      def last_sent_at=: (Integer) -> Integer
+
+      attr_accessor revoked_at: Integer?
+
+      attr_reader status: GrowsurfRuby::Models::AffiliateInvite::status?
+
+      def status=: (
+        GrowsurfRuby::Models::AffiliateInvite::status
+      ) -> GrowsurfRuby::Models::AffiliateInvite::status
+
+      def initialize: (
+        ?accepted_at: Integer?,
+        ?created_at: Integer,
+        ?email: String,
+        ?expires_at: Integer,
+        ?first_name: String?,
+        ?id: String,
+        ?last_name: String?,
+        ?last_sent_at: Integer,
+        ?revoked_at: Integer?,
+        ?status: GrowsurfRuby::Models::AffiliateInvite::status
+      ) -> void
+
+      def to_hash: -> {
+        accepted_at: Integer?,
+        created_at: Integer,
+        email: String,
+        expires_at: Integer,
+        first_name: String?,
+        id: String,
+        last_name: String?,
+        last_sent_at: Integer,
+        revoked_at: Integer?,
+        status: GrowsurfRuby::Models::AffiliateInvite::status
+      }
+
+      type status = :PENDING | :ACCEPTED | :EXPIRED | :REVOKED
+
+      module Status
+        extend GrowsurfRuby::Internal::Type::Enum
+
+        PENDING: :PENDING
+        ACCEPTED: :ACCEPTED
+        EXPIRED: :EXPIRED
+        REVOKED: :REVOKED
+
+        def self?.values: -> ::Array[GrowsurfRuby::Models::AffiliateInvite::status]
+      end
+    end
+  end
+end