growsurf-ruby 1.2.1 → 1.3.0

data/rbi/growsurf_ruby/resources/campaign.rbi

@@ -61,7 +61,7 @@ module GrowsurfRuby
       def list(request_options: {})
       end
 
-      # Creates a new program, plus any optional program rewards. The new program is
+      # 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(
@@ -82,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,
@@ -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,6 +204,57 @@ module GrowsurfRuby
       )
       end
 
+      # 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
@@ -315,9 +391,47 @@ module GrowsurfRuby
       )
       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, or derived rates — useful for detecting trends over time.
+      # 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,
@@ -338,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).
@@ -354,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/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

data/sig/growsurf_ruby/models/affiliate_invite_list_response.rbs

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

data/sig/growsurf_ruby/models/campaign/create.rbs

@@ -7,6 +7,7 @@ module GrowsurfRuby
           fingerprint: String,
           first_name: String,
           ip_address: String,
+          is_affiliate: bool,
           last_name: String,
           metadata: ::Hash[Symbol, top],
           mobile_instance_id: String,
@@ -29,6 +30,10 @@ module GrowsurfRuby
 
         def ip_address=: (String) -> String
 
+        attr_reader is_affiliate: bool?
+
+        def is_affiliate=: (bool) -> bool
+
         attr_reader last_name: String?
 
         def last_name=: (String) -> String
@@ -56,6 +61,7 @@ module GrowsurfRuby
           ?fingerprint: String,
           ?first_name: String,
           ?ip_address: String,
+          ?is_affiliate: bool,
           ?last_name: String,
           ?metadata: ::Hash[Symbol, top],
           ?mobile_instance_id: String,
@@ -68,6 +74,7 @@ module GrowsurfRuby
           fingerprint: String,
           first_name: String,
           ip_address: String,
+          is_affiliate: bool,
           last_name: String,
           metadata: ::Hash[Symbol, top],
           mobile_instance_id: String,