growsurf-ruby 1.2.0 → 1.3.0

data/lib/growsurf_ruby/resources/campaign.rb

@@ -76,10 +76,8 @@ module GrowsurfRuby
         )
       end
 
-      # Creates a program owned by the API key's bound team. Only `type` is required;
-      # everything else is server-defaulted. Editor-tab configuration (design, emails, options,
-      # installation) is not accepted here — configure it via the config sub-resources
-      # (e.g. `campaign.options.update`) 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.
       #
       # @overload create(type:, company_logo_image_url: nil, company_name: nil, currency_iso: nil, name: nil, rewards: nil, request_options: {})
       #
@@ -91,7 +89,7 @@ module GrowsurfRuby
       #
       # @param currency_iso [String] ISO 4217 currency code. Defaults to USD. Chosen when the program is created and immutable afterward — it cannot be changed on update.
       #
-      # @param name [String] The program name. Defaults to "Untitled Program".
+      # @param name [String] The program name. Defaults to a generated friendly label plus the creation date.
       #
       # @param rewards [Array<GrowsurfRuby::Models::Campaign::RewardCreateParams>] Optional inline rewards to create with the program.
       #
@@ -111,11 +109,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
-      # (`campaign.design`, `campaign.emails`, `campaign.options`, `campaign.installation`),
-      # 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.
       #
       # @overload update(id, company_logo_image_url: nil, company_name: nil, name: nil, status: nil, request_options: {})
       #
@@ -145,7 +143,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.
       #
       # @overload clone(id, request_options: {})
       #
@@ -163,6 +162,36 @@ 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.
+      #
+      # @overload create_affiliate_invite(id, email:, first_name: nil, last_name: nil, request_options: {})
+      #
+      # @param id [String] GrowSurf program ID.
+      #
+      # @param email [String] Valid email address to invite. Maximum 255 characters.
+      #
+      # @param first_name [String] Invitee first name, used in the invite email. Maximum 255 characters.
+      #
+      # @param last_name [String] Invitee last name. Maximum 255 characters.
+      #
+      # @param request_options [GrowsurfRuby::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [GrowsurfRuby::Models::AffiliateInvite]
+      #
+      # @see GrowsurfRuby::Models::CampaignCreateAffiliateInviteParams
+      def create_affiliate_invite(id, params)
+        parsed, options = GrowsurfRuby::CampaignCreateAffiliateInviteParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: ["campaign/%1$s/affiliate-invites", id],
+          body: parsed,
+          model: GrowsurfRuby::AffiliateInvite,
+          options: options
+        )
+      end
+
       # Some parameter documentations has been truncated, see
       # {GrowsurfRuby::Models::CampaignCreateMobileParticipantTokenParams} for more
       # details.
@@ -210,7 +239,69 @@ 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.
+      #
+      # @overload list_affiliate_applications(id, limit: nil, offset: nil, status: nil, request_options: {})
+      #
+      # @param id [String] GrowSurf program ID.
+      #
+      # @param limit [Integer] How many applications to return per page (1-100).
+      #
+      # @param offset [Integer] Offset number used to skip through a result set.
+      #
+      # @param status [Symbol, GrowsurfRuby::Models::CampaignListAffiliateApplicationsParams::Status] Only return applications with this status.
+      #
+      # @param request_options [GrowsurfRuby::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [GrowsurfRuby::Models::AffiliateApplicationListResponse]
+      #
+      # @see GrowsurfRuby::Models::CampaignListAffiliateApplicationsParams
+      def list_affiliate_applications(id, params = {})
+        parsed, options = GrowsurfRuby::CampaignListAffiliateApplicationsParams.dump_request(params)
+        query = GrowsurfRuby::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: ["campaign/%1$s/affiliate-applications", id],
+          query: query,
+          model: GrowsurfRuby::Models::AffiliateApplicationListResponse,
+          options: options
+        )
+      end
+
+      # Lists an affiliate program's enrollment invites, newest first.
+      #
+      # @overload list_affiliate_invites(id, limit: nil, offset: nil, status: nil, request_options: {})
+      #
+      # @param id [String] GrowSurf program ID.
+      #
+      # @param limit [Integer] How many invites to return per page (1-100).
+      #
+      # @param offset [Integer] Offset number used to skip through a result set.
+      #
+      # @param status [Symbol, GrowsurfRuby::Models::CampaignListAffiliateInvitesParams::Status] Only return invites with this status.
+      #
+      # @param request_options [GrowsurfRuby::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [GrowsurfRuby::Models::AffiliateInviteListResponse]
+      #
+      # @see GrowsurfRuby::Models::CampaignListAffiliateInvitesParams
+      def list_affiliate_invites(id, params = {})
+        parsed, options = GrowsurfRuby::CampaignListAffiliateInvitesParams.dump_request(params)
+        query = GrowsurfRuby::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: ["campaign/%1$s/affiliate-invites", id],
+          query: query,
+          model: GrowsurfRuby::Models::AffiliateInviteListResponse,
+          options: options
+        )
+      end
+
+      # **Affiliate programs only.** Retrieves a paged list of all participant
+      # commissions in an affiliate program.
       #
       # @overload list_commissions(id, limit: nil, next_id: nil, status: nil, request_options: {})
       #
@@ -301,7 +392,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.
       #
       # @overload list_payouts(id, limit: nil, next_id: nil, status: nil, request_options: {})
       #
@@ -378,10 +470,72 @@ module GrowsurfRuby
         )
       end
 
+      # 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.
+      #
+      # @overload resend_affiliate_invite(invite_id, id:, request_options: {})
+      #
+      # @param invite_id [String] Affiliate invite ID.
+      #
+      # @param id [String] GrowSurf program ID.
+      #
+      # @param request_options [GrowsurfRuby::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [GrowsurfRuby::Models::AffiliateInvite]
+      #
+      # @see GrowsurfRuby::Models::CampaignResendAffiliateInviteParams
+      def resend_affiliate_invite(invite_id, params)
+        parsed, options = GrowsurfRuby::CampaignResendAffiliateInviteParams.dump_request(params)
+        id =
+          parsed.delete(:id) do
+            raise ArgumentError.new("missing required path argument #{_1}")
+          end
+        @client.request(
+          method: :post,
+          path: ["campaign/%1$s/affiliate-invites/%2$s/resend", id, invite_id],
+          model: GrowsurfRuby::AffiliateInvite,
+          options: options
+        )
+      end
+
+      # Returns one affiliate application, including its submitted form answers.
+      #
+      # @overload retrieve_affiliate_application(application_id, id:, request_options: {})
+      #
+      # @param application_id [String] Affiliate application ID.
+      #
+      # @param id [String] GrowSurf program ID.
+      #
+      # @param request_options [GrowsurfRuby::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [GrowsurfRuby::Models::AffiliateApplication]
+      #
+      # @see GrowsurfRuby::Models::CampaignRetrieveAffiliateApplicationParams
+      def retrieve_affiliate_application(application_id, params)
+        parsed, options = GrowsurfRuby::CampaignRetrieveAffiliateApplicationParams.dump_request(params)
+        id =
+          parsed.delete(:id) do
+            raise ArgumentError.new("missing required path argument #{_1}")
+          end
+        @client.request(
+          method: :get,
+          path: ["campaign/%1$s/affiliate-applications/%2$s", id, application_id],
+          model: GrowsurfRuby::AffiliateApplication,
+          options: options
+        )
+      end
+
       # Some parameter documentations has been truncated, see
       # {GrowsurfRuby::Models::CampaignRetrieveAnalyticsParams} for more details.
       #
-      # Retrieves analytics for a program.
+      # 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.
       #
       # @overload retrieve_analytics(id, days: nil, end_date: nil, include: nil, interval: nil, start_date: nil, request_options: {})
       #
@@ -391,7 +545,7 @@ module GrowsurfRuby
       #
       # @param end_date [Integer] End date of the analytics timeframe as a Unix timestamp in milliseconds. Require
       #
-      # @param include [String] Comma-separated list of optional enrichments (opt-in to keep the default response
+      # @param include [String] Comma-separated list of optional data to include: `previousPeriod` adds totals for
       #
       # @param interval [Symbol, GrowsurfRuby::Models::CampaignRetrieveAnalyticsParams::Interval] When set to `day`, `week`, or `month`, the response also includes a `series` array
       #
@@ -414,6 +568,82 @@ module GrowsurfRuby
         )
       end
 
+      # Some parameter documentations has been truncated, see
+      # {GrowsurfRuby::Models::CampaignReviewAffiliateApplicationParams} for more
+      # details.
+      #
+      # 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.
+      #
+      # @overload review_affiliate_application(application_id, id:, allow_immediate_reapply: nil, reapply_allowed_at: nil, rejection_reason: nil, review_note: nil, status: nil, request_options: {})
+      #
+      # @param application_id [String] Affiliate application ID.
+      #
+      # @param id [String] GrowSurf program ID.
+      #
+      # @param allow_immediate_reapply [Boolean] Only valid when `status` is `DENIED`; let the applicant reapply right away
+      #
+      # @param reapply_allowed_at [Integer] For an already-denied application, move the reapplication window to this earlier
+      #
+      # @param rejection_reason [String] Short reason recorded with a denial. Only valid when `status` is `DENIED`. Maximum 255 characters.
+      #
+      # @param review_note [String] Private note recorded with a denial. Only valid when `status` is `DENIED`; never shown to the applicant. Maximum 500 characters.
+      #
+      # @param status [Symbol, GrowsurfRuby::Models::CampaignReviewAffiliateApplicationParams::Status] The decision. `APPROVED` enrolls the applicant as an affiliate; `DENIED` closes
+      #
+      # @param request_options [GrowsurfRuby::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [GrowsurfRuby::Models::AffiliateApplication]
+      #
+      # @see GrowsurfRuby::Models::CampaignReviewAffiliateApplicationParams
+      def review_affiliate_application(application_id, params)
+        parsed, options = GrowsurfRuby::CampaignReviewAffiliateApplicationParams.dump_request(params)
+        id =
+          parsed.delete(:id) do
+            raise ArgumentError.new("missing required path argument #{_1}")
+          end
+        @client.request(
+          method: :patch,
+          path: ["campaign/%1$s/affiliate-applications/%2$s", id, application_id],
+          body: parsed,
+          model: GrowsurfRuby::AffiliateApplication,
+          options: options
+        )
+      end
+
+      # Revokes a pending invite. Its emailed accept link stops working immediately.
+      #
+      # @overload revoke_affiliate_invite(invite_id, id:, request_options: {})
+      #
+      # @param invite_id [String] Affiliate invite ID.
+      #
+      # @param id [String] GrowSurf program ID.
+      #
+      # @param request_options [GrowsurfRuby::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [GrowsurfRuby::Models::AffiliateInvite]
+      #
+      # @see GrowsurfRuby::Models::CampaignRevokeAffiliateInviteParams
+      def revoke_affiliate_invite(invite_id, params)
+        parsed, options = GrowsurfRuby::CampaignRevokeAffiliateInviteParams.dump_request(params)
+        id =
+          parsed.delete(:id) do
+            raise ArgumentError.new("missing required path argument #{_1}")
+          end
+        @client.request(
+          method: :delete,
+          path: ["campaign/%1$s/affiliate-invites/%2$s", id, invite_id],
+          model: GrowsurfRuby::AffiliateInvite,
+          options: options
+        )
+      end
+
       # @api private
       #
       # @param client [GrowsurfRuby::Client]

data/lib/growsurf_ruby/resources/team.rb

@@ -3,9 +3,9 @@
 module GrowsurfRuby
   module Resources
     class Team
-      # Retrieves the team bound to the API key or OAuth connection. A credential that
-      # can act across multiple teams cannot use this operation because it has no single
-      # Team resource.
+      # 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.
       #
       # @overload retrieve(request_options: {})
       #
@@ -21,8 +21,9 @@ module GrowsurfRuby
         )
       end
 
-      # Updates the name of the team bound to the API key or OAuth connection. Any
-      # other property is rejected with a `400`.
+      # 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.
       #
       # @overload update(name:, request_options: {})
       #
@@ -44,11 +45,15 @@ module GrowsurfRuby
         )
       end
 
-      # Generates a new API key and makes the key used on this request stop working
-      # when rotation succeeds. The SDK sends a retry-safe `Idempotency-Key`, so
-      # automatic retries return the same replacement. Store the new key, then update
-      # every integration that used the old key. This operation is unavailable through
-      # MCP.
+      # 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.
       #
       # @overload rotate_api_key(request_options: {})
       #
@@ -64,8 +69,9 @@ module GrowsurfRuby
         )
       end
 
-      # Requests GrowSurf verification for the bound team. Calling this again while a
-      # request is pending does not create a duplicate.
+      # 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`.
       #
       # @overload request_verification(request_options: {})
       #
@@ -82,7 +88,10 @@ module GrowsurfRuby
       end
 
       # Resends the email-verification message to the bound team's owner. The response
-      # never reveals the owner's email address.
+      # 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.
       #
       # @overload resend_owner_verification_email(request_options: {})
       #

data/lib/growsurf_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GrowsurfRuby
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

data/lib/growsurf_ruby.rb

@@ -63,6 +63,7 @@ require_relative "growsurf_ruby/models/campaign/delete_reward_response"
 require_relative "growsurf_ruby/models/campaign/fraud_risk_level"
 require_relative "growsurf_ruby/models/campaign/participant_activity_logs_response"
 require_relative "growsurf_ruby/models/campaign/participant_add_params"
+require_relative "growsurf_ruby/models/email_analytics"
 require_relative "growsurf_ruby/models/campaign/participant_analytics_response"
 require_relative "growsurf_ruby/models/campaign/participant_bulk_delete_params"
 require_relative "growsurf_ruby/models/campaign/participant_bulk_delete_response"
@@ -72,6 +73,8 @@ require_relative "growsurf_ruby/models/campaign/participant_delete_params"
 require_relative "growsurf_ruby/models/campaign/participant_delete_response"
 require_relative "growsurf_ruby/models/campaign/participant_email_params"
 require_relative "growsurf_ruby/models/campaign/participant_email_response"
+require_relative "growsurf_ruby/models/campaign/participant_get_payout_destination_params"
+require_relative "growsurf_ruby/models/campaign/participant_get_payout_destination_response"
 require_relative "growsurf_ruby/models/campaign/participant_list_activity_logs_params"
 require_relative "growsurf_ruby/models/campaign/participant_list_commissions_params"
 require_relative "growsurf_ruby/models/campaign/participant_list_payouts_params"
@@ -82,6 +85,8 @@ require_relative "growsurf_ruby/models/campaign/participant_record_transaction_p
 require_relative "growsurf_ruby/models/campaign/participant_record_transaction_response"
 require_relative "growsurf_ruby/models/campaign/participant_refund_transaction_params"
 require_relative "growsurf_ruby/models/campaign/participant_refund_transaction_response"
+require_relative "growsurf_ruby/models/campaign/participant_request_payout_destination_confirmation_params"
+require_relative "growsurf_ruby/models/campaign/participant_request_payout_destination_confirmation_response"
 require_relative "growsurf_ruby/models/campaign/participant_retrieve_analytics_params"
 require_relative "growsurf_ruby/models/campaign/participant_retrieve_params"
 require_relative "growsurf_ruby/models/campaign/participant_reward"
@@ -112,14 +117,21 @@ require_relative "growsurf_ruby/models/campaign/webhook_test_response"
 require_relative "growsurf_ruby/models/campaign/webhook_update_params"
 require_relative "growsurf_ruby/models/account_create_params"
 require_relative "growsurf_ruby/models/account_create_response"
+require_relative "growsurf_ruby/models/affiliate_application"
+require_relative "growsurf_ruby/models/affiliate_application_list_response"
+require_relative "growsurf_ruby/models/affiliate_invite"
+require_relative "growsurf_ruby/models/affiliate_invite_list_response"
 require_relative "growsurf_ruby/models/team"
 require_relative "growsurf_ruby/models/team_resend_owner_verification_email_response"
 require_relative "growsurf_ruby/models/team_rotate_api_key_response"
 require_relative "growsurf_ruby/models/team_update_params"
 require_relative "growsurf_ruby/models/campaign"
+require_relative "growsurf_ruby/models/campaign_create_affiliate_invite_params"
 require_relative "growsurf_ruby/models/campaign_create_mobile_participant_token_params"
 require_relative "growsurf_ruby/models/campaign_create_mobile_participant_token_response"
 require_relative "growsurf_ruby/models/campaign_create_params"
+require_relative "growsurf_ruby/models/campaign_list_affiliate_applications_params"
+require_relative "growsurf_ruby/models/campaign_list_affiliate_invites_params"
 require_relative "growsurf_ruby/models/campaign_list_commissions_params"
 require_relative "growsurf_ruby/models/campaign_list_leaderboard_params"
 require_relative "growsurf_ruby/models/campaign_list_params"
@@ -127,9 +139,13 @@ require_relative "growsurf_ruby/models/campaign_list_participants_params"
 require_relative "growsurf_ruby/models/campaign_list_payouts_params"
 require_relative "growsurf_ruby/models/campaign_list_referrals_params"
 require_relative "growsurf_ruby/models/campaign_list_response"
+require_relative "growsurf_ruby/models/campaign_resend_affiliate_invite_params"
+require_relative "growsurf_ruby/models/campaign_retrieve_affiliate_application_params"
 require_relative "growsurf_ruby/models/campaign_retrieve_analytics_params"
 require_relative "growsurf_ruby/models/campaign_retrieve_analytics_response"
 require_relative "growsurf_ruby/models/campaign_retrieve_params"
+require_relative "growsurf_ruby/models/campaign_review_affiliate_application_params"
+require_relative "growsurf_ruby/models/campaign_revoke_affiliate_invite_params"
 require_relative "growsurf_ruby/models/campaign_update_params"
 require_relative "growsurf_ruby/models/commission_structure"
 require_relative "growsurf_ruby/models/participant_commission_list"