growsurf-ruby 1.3.0 → 1.5.0

data/rbi/growsurf_ruby/resources/campaign/program_resources.rbi

@@ -0,0 +1,116 @@
+# typed: strong
+
+module GrowsurfRuby
+  module Resources
+    class Campaign
+      class ProgramResources
+        sig do
+          params(
+            id: String,
+            request_options: GrowsurfRuby::RequestOptions::OrHash
+          ).returns(GrowsurfRuby::Campaign::ProgramResourceListResponse)
+        end
+        def list(id, request_options: {})
+        end
+
+        sig do
+          params(
+            id: String,
+            type:
+              GrowsurfRuby::Campaign::ProgramResourceCreateParams::Type::OrSymbol,
+            title: String,
+            description: T.nilable(String),
+            category: T.nilable(String),
+            is_published: T::Boolean,
+            url: String,
+            text: String,
+            upload_ticket: String,
+            upload_result: GrowsurfRuby::Campaign::ProgramResourceUploadResult::OrHash,
+            request_options: GrowsurfRuby::RequestOptions::OrHash
+          ).returns(GrowsurfRuby::Campaign::ProgramResource)
+        end
+        def create(
+          id,
+          type:,
+          title:,
+          description: nil,
+          category: nil,
+          is_published: nil,
+          url: nil,
+          text: nil,
+          upload_ticket: nil,
+          upload_result: nil,
+          request_options: {}
+        )
+        end
+
+        sig do
+          params(
+            resource_id: String,
+            id: String,
+            type:
+              GrowsurfRuby::Campaign::ProgramResourceUpdateParams::Type::OrSymbol,
+            title: String,
+            description: T.nilable(String),
+            category: T.nilable(String),
+            is_published: T::Boolean,
+            position: Integer,
+            url: String,
+            text: String,
+            upload_ticket: String,
+            upload_result: GrowsurfRuby::Campaign::ProgramResourceUploadResult::OrHash,
+            request_options: GrowsurfRuby::RequestOptions::OrHash
+          ).returns(GrowsurfRuby::Campaign::ProgramResource)
+        end
+        def update(
+          resource_id,
+          id:,
+          type: nil,
+          title: nil,
+          description: nil,
+          category: nil,
+          is_published: nil,
+          position: nil,
+          url: nil,
+          text: nil,
+          upload_ticket: nil,
+          upload_result: nil,
+          request_options: {}
+        )
+        end
+
+        sig do
+          params(
+            resource_id: String,
+            id: String,
+            request_options: GrowsurfRuby::RequestOptions::OrHash
+          ).returns(GrowsurfRuby::Campaign::DeleteProgramResourceResponse)
+        end
+        def delete(resource_id, id:, request_options: {})
+        end
+
+        sig do
+          params(
+            id: String,
+            file_name: String,
+            mime_type: String,
+            bytes: Integer,
+            request_options: GrowsurfRuby::RequestOptions::OrHash
+          ).returns(GrowsurfRuby::Campaign::ProgramResourceUploadTicket)
+        end
+        def create_upload_ticket(
+          id,
+          file_name:,
+          mime_type:,
+          bytes:,
+          request_options: {}
+        )
+        end
+
+        sig { params(client: GrowsurfRuby::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

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

@@ -24,7 +24,8 @@ module GrowsurfRuby
         # The reward type must be compatible with the program type (affiliate programs
         # support only `AFFILIATE` rewards; referral programs support all other types).
         # Enabling an active reward of a type automatically enables that reward type on
-        # the program.
+        # the program. For an affiliate reward, `commissionStructure.event: LEAD`
+        # requires a `FIXED` commission with a positive `amount`.
         sig do
           params(
             id: String,
@@ -32,21 +33,23 @@ module GrowsurfRuby
               GrowsurfRuby::Models::Campaign::RewardCreateParams::Type::OrSymbol,
             commission_structure: GrowsurfRuby::CommissionStructure::OrHash,
             conversions_required: Integer,
-            coupon_code: String,
+            coupon_code: T.nilable(String),
             description: String,
-            image_url: String,
+            event:
+              GrowsurfRuby::Models::Campaign::RewardCreateParams::Event::OrSymbol,
+            image_url: T.nilable(String),
             is_unlimited: T::Boolean,
             is_visible: T::Boolean,
             limit: Integer,
             limit_duration:
               GrowsurfRuby::Models::Campaign::RewardCreateParams::LimitDuration::OrSymbol,
             metadata: T::Hash[Symbol, T.anything],
-            next_milestone_prefix: String,
-            next_milestone_suffix: String,
+            next_milestone_prefix: T.nilable(String),
+            next_milestone_suffix: T.nilable(String),
             number_of_winners: Integer,
             order: Integer,
-            referral_coupon_code: String,
-            referral_description: String,
+            referral_coupon_code: T.nilable(String),
+            referral_description: T.nilable(String),
             referred_reward_upfront: T::Boolean,
             referred_value: GrowsurfRuby::RewardTaxValuation::OrHash,
             title: String,
@@ -59,7 +62,9 @@ module GrowsurfRuby
           id,
           # Body param: The reward type. Immutable after creation.
           type:,
-          # Body param
+          # Body param: The affiliate commission structure. Required when creating an
+          # `AFFILIATE` reward. A `FIXED` commission requires `amount`; a `PERCENT`
+          # commission requires `percent`.
           commission_structure: nil,
           # Body param
           conversions_required: nil,
@@ -69,6 +74,11 @@ module GrowsurfRuby
           coupon_code: nil,
           # Body param
           description: nil,
+          # Body param: The referral event that earns this Campaign Reward. Use `LEAD` or
+          # `CONVERSION`. `LEAD` requires the program installation's `referralTrigger` to
+          # be `CUSTOM`. This field applies only to `SINGLE_SIDED`, `DOUBLE_SIDED`, and
+          # `MILESTONE` rewards. When omitted, it defaults to `CONVERSION`.
+          event: nil,
           # Body param
           image_url: nil,
           # Body param: Whether the reward can be earned an unlimited number of times.
@@ -121,28 +131,31 @@ module GrowsurfRuby
         # immutable and cannot be changed. When the update replaces `metadata`, renamed
         # keys automatically rewrite any `{{campaignReward[…]}}` references in campaign
         # copy; removing a key that campaign copy still references returns a `409` listing
-        # the referencing fields.
+        # the referencing fields. For an affiliate reward, `commissionStructure.event:
+        # LEAD` requires a `FIXED` commission with a positive `amount`.
         sig do
           params(
             campaign_reward_id: String,
             id: String,
             commission_structure: GrowsurfRuby::CommissionStructure::OrHash,
             conversions_required: Integer,
-            coupon_code: String,
+            coupon_code: T.nilable(String),
             description: String,
-            image_url: String,
+            event:
+              GrowsurfRuby::Models::Campaign::RewardUpdateParams::Event::OrSymbol,
+            image_url: T.nilable(String),
             is_unlimited: T::Boolean,
             is_visible: T::Boolean,
             limit: Integer,
             limit_duration:
               GrowsurfRuby::Models::Campaign::RewardUpdateParams::LimitDuration::OrSymbol,
             metadata: T::Hash[Symbol, T.anything],
-            next_milestone_prefix: String,
-            next_milestone_suffix: String,
+            next_milestone_prefix: T.nilable(String),
+            next_milestone_suffix: T.nilable(String),
             number_of_winners: Integer,
             order: Integer,
-            referral_coupon_code: String,
-            referral_description: String,
+            referral_coupon_code: T.nilable(String),
+            referral_description: T.nilable(String),
             referred_reward_upfront: T::Boolean,
             referred_value: GrowsurfRuby::RewardTaxValuation::OrHash,
             title: String,
@@ -155,7 +168,8 @@ module GrowsurfRuby
           campaign_reward_id,
           # Path param: GrowSurf program ID.
           id:,
-          # Body param
+          # Body param: The affiliate commission structure. A `FIXED` commission requires
+          # `amount`; a `PERCENT` commission requires `percent`.
           commission_structure: nil,
           # Body param
           conversions_required: nil,
@@ -165,6 +179,11 @@ module GrowsurfRuby
           coupon_code: nil,
           # Body param
           description: nil,
+          # Body param: The referral event that earns this Campaign Reward. Use `LEAD` or
+          # `CONVERSION`. `LEAD` requires the program installation's `referralTrigger` to
+          # be `CUSTOM`. This field applies only to `SINGLE_SIDED`, `DOUBLE_SIDED`, and
+          # `MILESTONE` rewards. When omitted, the stored event is preserved.
+          event: nil,
           # Body param
           image_url: nil,
           # Body param: Whether the reward can be earned an unlimited number of times.

data/rbi/growsurf_ruby/resources/campaign.rbi

@@ -18,6 +18,10 @@ module GrowsurfRuby
       sig { returns(GrowsurfRuby::Resources::Campaign::Rewards) }
       attr_reader :rewards
 
+      # Program Resource management and secure FILE upload operations.
+      sig { returns(GrowsurfRuby::Resources::Campaign::ProgramResources) }
+      attr_reader :resources
+
       # Program Editor "Design" tab configuration operations.
       sig { returns(GrowsurfRuby::Resources::Campaign::Design) }
       attr_reader :design
@@ -34,6 +38,10 @@ module GrowsurfRuby
       sig { returns(GrowsurfRuby::Resources::Campaign::Installation) }
       attr_reader :installation
 
+      # Integration status operations.
+      sig { returns(GrowsurfRuby::Resources::Campaign::Integrations) }
+      attr_reader :integrations
+
       # Program webhook configuration operations.
       sig { returns(GrowsurfRuby::Resources::Campaign::Webhooks) }
       attr_reader :webhooks
@@ -69,6 +77,7 @@ module GrowsurfRuby
           company_logo_image_url: String,
           company_name: String,
           currency_iso: String,
+          goal: GrowsurfRuby::CampaignCreateParams::Goal::OrSymbol,
           name: String,
           rewards: T::Array[GrowsurfRuby::Campaign::RewardCreateParams::OrHash],
           request_options: GrowsurfRuby::RequestOptions::OrHash
@@ -82,6 +91,11 @@ 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,
+        # What the program is for, which seeds share settings that suit that audience.
+        # Programs selling to businesses start with the LinkedIn share button visible;
+        # consumer, financial, education, insurance, newsletter, and waitlist programs
+        # start with it hidden. Set only when the program is created.
+        goal: nil,
         # The program name. Defaults to a generated friendly label plus the creation date.
         name: nil,
         # Optional inline rewards to create with the program.
@@ -428,10 +442,9 @@ module GrowsurfRuby
 
       # 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.
+      # derived rates, email performance, or participant engagement. Add `engagement` for
+      # covered activity totals, comparisons, series, and breakdowns. Unknown coverage returns
+      # explicit unavailable states rather than zeroes.
       sig do
         params(
           id: String,
@@ -440,7 +453,10 @@ module GrowsurfRuby
           include: String,
           interval:
             GrowsurfRuby::CampaignRetrieveAnalyticsParams::Interval::OrSymbol,
+          platform:
+            GrowsurfRuby::CampaignRetrieveAnalyticsParams::Platform::OrSymbol,
           start_date: Integer,
+          timezone: String,
           request_options: GrowsurfRuby::RequestOptions::OrHash
         ).returns(GrowsurfRuby::Models::CampaignRetrieveAnalyticsResponse)
       end
@@ -462,11 +478,43 @@ module GrowsurfRuby
         # 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).
+        # with per-period totals and uses the same bucket size for `engagement.series`.
+        # Defaults to `total` (no legacy series); `engagement.series` uses daily buckets when
+        # `interval` is `total` or omitted.
         interval: nil,
+        # Participant platform used for `engagement`. Defaults to `ALL`.
+        platform: nil,
         # Start date of the analytics timeframe as a Unix timestamp in milliseconds.
         # Required if `days` is not set.
         start_date: nil,
+        # IANA timezone used for engagement periods and buckets. Defaults to `UTC`.
+        timezone: nil,
+        request_options: {}
+      )
+      end
+
+      # Retrieves activation cohorts for a program. Coverage states distinguish unknown values
+      # from zeroes.
+      sig do
+        params(
+          id: String,
+          cohort_from: Integer,
+          cohort_to: Integer,
+          cohort_interval:
+            GrowsurfRuby::CampaignRetrieveActivationAnalyticsParams::CohortInterval::OrSymbol,
+          observation_window_days:
+            GrowsurfRuby::CampaignRetrieveActivationAnalyticsParams::ObservationWindowDays::OrInteger,
+          timezone: String,
+          request_options: GrowsurfRuby::RequestOptions::OrHash
+        ).returns(GrowsurfRuby::Models::CampaignActivationAnalyticsResponse)
+      end
+      def retrieve_activation_analytics(
+        id,
+        cohort_from: nil,
+        cohort_to: nil,
+        cohort_interval: nil,
+        observation_window_days: nil,
+        timezone: nil,
         request_options: {}
       )
       end

data/rbi/growsurf_ruby/resources/team.rbi

@@ -54,11 +54,13 @@ 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.
+      # Resends the email-verification message to the owner of the account the API key
+      # belongs to. This is the recovery path for a `403` with error code
+      # `EMAIL_NOT_VERIFIED_ERROR`, so it stays callable with any GrowSurf API key while the
+      # rest of the API is locked. 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/internal/type/base_model.rbs

@@ -85,6 +85,12 @@ module GrowsurfRuby
 
         def deep_to_h: -> ::Hash[Symbol, top]
 
+        attr_reader response_headers: ::Hash[String, String]
+
+        def attach_response_headers: (
+          ::Hash[String, String] headers
+        ) -> instance
+
         def deconstruct_keys: (::Array[Symbol]? keys) -> ::Hash[Symbol, top]
 
         def to_json: (*top a) -> String

data/sig/growsurf_ruby/internal/type/base_page.rbs

@@ -12,6 +12,8 @@ module GrowsurfRuby
 
         alias enum_for to_enum
 
+        attr_reader response_headers: ::Hash[String, String]
+
         def initialize: (
           client: GrowsurfRuby::Internal::Transport::BaseClient,
           req: GrowsurfRuby::Internal::Transport::BaseClient::request_components,

data/sig/growsurf_ruby/models/analytics_availability.rbs

@@ -0,0 +1,15 @@
+module GrowsurfRuby
+  module Models
+    type analytics_availability = :AVAILABLE | :PARTIAL | :UNAVAILABLE
+
+    module AnalyticsAvailability
+      extend GrowsurfRuby::Internal::Type::Enum
+
+      AVAILABLE: :AVAILABLE
+      PARTIAL: :PARTIAL
+      UNAVAILABLE: :UNAVAILABLE
+
+      def self?.values: -> ::Array[GrowsurfRuby::Models::analytics_availability]
+    end
+  end
+end

data/sig/growsurf_ruby/models/analytics_unavailable_reason.rbs

@@ -0,0 +1,26 @@
+module GrowsurfRuby
+  module Models
+    type analytics_unavailable_reason =
+      :COVERAGE_UNAVAILABLE
+      | :PRE_COVERAGE
+      | :PARTIAL_COVERAGE
+      | :INSUFFICIENT_COVERAGE
+      | :EMPTY_DENOMINATOR
+      | :QUERY_LIMIT_EXCEEDED
+      | :PARTICIPANT_NOT_ELIGIBLE
+
+    module AnalyticsUnavailableReason
+      extend GrowsurfRuby::Internal::Type::Enum
+
+      COVERAGE_UNAVAILABLE: :COVERAGE_UNAVAILABLE
+      PRE_COVERAGE: :PRE_COVERAGE
+      PARTIAL_COVERAGE: :PARTIAL_COVERAGE
+      INSUFFICIENT_COVERAGE: :INSUFFICIENT_COVERAGE
+      EMPTY_DENOMINATOR: :EMPTY_DENOMINATOR
+      QUERY_LIMIT_EXCEEDED: :QUERY_LIMIT_EXCEEDED
+      PARTICIPANT_NOT_ELIGIBLE: :PARTICIPANT_NOT_ELIGIBLE
+
+      def self?.values: -> ::Array[GrowsurfRuby::Models::analytics_unavailable_reason]
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+module GrowsurfRuby
+  module Models
+    module Campaign
+      type delete_program_resource_response = { id: String, success: bool }
+
+      class DeleteProgramResourceResponse < GrowsurfRuby::Internal::Type::BaseModel
+        attr_accessor id: String
+        attr_accessor success: bool
+        def initialize: (id: String, success: bool) -> void
+        def to_hash: -> delete_program_resource_response
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+module GrowsurfRuby
+  module Models
+    module Campaign
+      type integration =
+        {
+          id: String,
+          auto_disabled: bool,
+          connect_url: String,
+          connected: bool,
+          enabled: bool,
+          name: String
+        }
+
+      class Integration < GrowsurfRuby::Internal::Type::BaseModel
+        attr_accessor id: String
+
+        attr_accessor auto_disabled: bool
+
+        attr_accessor connect_url: String
+
+        attr_accessor connected: bool
+
+        attr_accessor enabled: bool
+
+        attr_accessor name: String
+
+        def initialize: (
+          id: String,
+          auto_disabled: bool,
+          connect_url: String,
+          connected: bool,
+          enabled: bool,
+          name: String
+        ) -> void
+
+        def to_hash: -> {
+          id: String,
+          auto_disabled: bool,
+          connect_url: String,
+          connected: bool,
+          enabled: bool,
+          name: String
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+module GrowsurfRuby
+  module Models
+    module Campaign
+      type integration_list_response =
+        { integrations: ::Array[GrowsurfRuby::Campaign::Integration] }
+
+      class IntegrationListResponse < GrowsurfRuby::Internal::Type::BaseModel
+        attr_accessor integrations: ::Array[GrowsurfRuby::Campaign::Integration]
+
+        def initialize: (
+          integrations: ::Array[GrowsurfRuby::Campaign::Integration]
+        ) -> void
+
+        def to_hash: -> {
+          integrations: ::Array[GrowsurfRuby::Campaign::Integration]
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+module GrowsurfRuby
+  module Models
+    module Campaign
+      class ParticipantActivationAnalytics < GrowsurfRuby::Internal::Type::BaseModel
+        type program_type = :REFERRAL | :AFFILIATE
+        type anchor_field = :enrolledAsAdvocateAt | :approvedAsAffiliateAt
+        type share_channel =
+          :email
+          | :facebook
+          | :twitter
+          | :linkedin
+          | :pinterest
+          | :threads
+          | :bluesky
+          | :sms
+          | :messenger
+          | :whatsapp
+          | :wechat
+          | :telegram
+          | :reddit
+          | :tumblr
+          | :qrcode
+          | :copyRefLink
+          | :iosNativeShare
+          | :androidNativeShare
+
+        attr_accessor coverage_start_at: Integer?
+        attr_accessor metric_contract_version: Integer
+        attr_accessor program_type: GrowsurfRuby::Models::Campaign::ParticipantActivationAnalytics::program_type
+        attr_accessor state: GrowsurfRuby::Models::analytics_availability
+        attr_accessor reason: GrowsurfRuby::Models::analytics_unavailable_reason?
+        attr_accessor cohort: GrowsurfRuby::Models::Campaign::ParticipantActivationAnalytics::Cohort
+        attr_accessor enrolled_as_advocate_at: Integer?
+        attr_accessor milestones: GrowsurfRuby::Models::Campaign::ParticipantActivationAnalytics::Milestones
+        def initialize: (**untyped) -> void
+
+        module ProgramType
+          extend GrowsurfRuby::Internal::Type::Enum
+          REFERRAL: :REFERRAL
+          AFFILIATE: :AFFILIATE
+          def self?.values: -> ::Array[GrowsurfRuby::Models::Campaign::ParticipantActivationAnalytics::program_type]
+        end
+
+        module AnchorField
+          extend GrowsurfRuby::Internal::Type::Enum
+          ENROLLED_AS_ADVOCATE_AT: :enrolledAsAdvocateAt
+          APPROVED_AS_AFFILIATE_AT: :approvedAsAffiliateAt
+          def self?.values: -> ::Array[GrowsurfRuby::Models::Campaign::ParticipantActivationAnalytics::anchor_field]
+        end
+
+        module ShareChannel
+          extend GrowsurfRuby::Internal::Type::Enum
+          EMAIL: :email
+          FACEBOOK: :facebook
+          TWITTER: :twitter
+          LINKEDIN: :linkedin
+          PINTEREST: :pinterest
+          THREADS: :threads
+          BLUESKY: :bluesky
+          SMS: :sms
+          MESSENGER: :messenger
+          WHATSAPP: :whatsapp
+          WECHAT: :wechat
+          TELEGRAM: :telegram
+          REDDIT: :reddit
+          TUMBLR: :tumblr
+          QRCODE: :qrcode
+          COPY_REF_LINK: :copyRefLink
+          IOS_NATIVE_SHARE: :iosNativeShare
+          ANDROID_NATIVE_SHARE: :androidNativeShare
+          def self?.values: -> ::Array[GrowsurfRuby::Models::Campaign::ParticipantActivationAnalytics::share_channel]
+        end
+
+        class Cohort < GrowsurfRuby::Internal::Type::BaseModel
+          attr_accessor anchor_field: GrowsurfRuby::Models::Campaign::ParticipantActivationAnalytics::anchor_field
+          attr_accessor anchor_at: Integer?
+          def initialize: (**untyped) -> void
+        end
+
+        class Milestones < GrowsurfRuby::Internal::Type::BaseModel
+          attr_accessor first_portal_viewed_at: Integer?
+          attr_accessor first_referral_link_copied_at: Integer?
+          attr_accessor first_share_at: Integer?
+          attr_accessor first_share_channel: GrowsurfRuby::Models::Campaign::ParticipantActivationAnalytics::share_channel?
+          attr_accessor first_unique_click_at: Integer?
+          attr_accessor first_lead_at: Integer?
+          attr_accessor first_referral_at: Integer?
+          attr_accessor first_reward_at: Integer?
+          attr_accessor first_commission_at: Integer?
+          attr_accessor payout_setup_completed_at: Integer?
+          def initialize: (**untyped) -> void
+        end
+      end
+    end
+  end
+end