growsurf-ruby 1.2.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42193bcccd25c0e13bb8fe762d66313d57b6c673b820322dc1a633dc8d3cd70e
-  data.tar.gz: 6280026d747b838e22cdf1db95a0f07eed13b0d049efca6af74d46e99f833f3a
+  metadata.gz: d3f7355b6a4f09692cd4f02923eda76fe0887f88b647f0cfdc461b93e36337f6
+  data.tar.gz: 16ae21e1f33b5f0ffead7caf1f93d80758fbffce09c3d634d0350f5cde7e1e36
 SHA512:
-  metadata.gz: 7ec17bcbb93999329df4edd4c5d0e64e1385e9278c4168059d3f66817e49bf3e3463f0ab3c8cbef14742f9ee6bd3efc6461da26e53d11a4bced6120352da2c3f
-  data.tar.gz: cf651a17a07aa569619bc58d2e90c9d236ec8d7a2aebf9b10102d38dca72b120f2514d06eeb5853919235ab2e466e71db2c45cc937ae27b9cb7fbbe817922185
+  metadata.gz: c58b6e6dd858d7c7e419bd5d96d605b27d8de8518d3c9c2ff2c4dd121473404a6843f0e62dc6c4b0190c02ae7bed3821542b73ab5ebf9bf3646ee343783a92ee
+  data.tar.gz: d98124e2a70ebb54f25757c814342a2ee6f4d5595c3713ebb26386b9157474eaee6ad35825ad091f5b180455d89d9a334972fd37e53593c1c066d3d3d7b7f553

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.2.1](https://github.com/growsurf/growsurf-ruby/compare/v1.2.0...v1.2.1) (2026-07-14)
+
+
+### Bug Fixes
+
+* align method docs with the REST v2 contract ([11967f2](https://github.com/growsurf/growsurf-ruby/commit/11967f2d1b95266e921775b921db970fc11e3cbb))
+
 ## [1.2.0](https://github.com/growsurf/growsurf-ruby/compare/v1.1.2...v1.2.0) (2026-07-13)
 
 

data/README.md

@@ -17,7 +17,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "growsurf-ruby", "~> 1.2.0"
+gem "growsurf-ruby", "~> 1.2.1"
 ```
 
 <!-- x-release-please-end -->

data/lib/growsurf_ruby/resources/account.rb

@@ -3,10 +3,20 @@
 module GrowsurfRuby
   module Resources
     class Account
-      # Creates a new GrowSurf account and returns an API key shown once in the
-      # response. The key is locked until the team owner's email address is verified and
-      # rotates the first time the account owner signs in to the GrowSurf dashboard.
+      # Creates a new GrowSurf account. This is the only endpoint that does not require
+      # an API key. The response includes an API key for the new account, shown once in
+      # the response. The key is locked until the team owner's email address is
+      # verified: authenticated program and resource endpoints return a `403` with error
+      # code `EMAIL_NOT_VERIFIED_ERROR` until then (resend the email via `POST
+      # /team/owner/verification-email`, then retry). A welcome email is sent to the
+      # address with the verification link and a set-password link for dashboard access.
       # Accounts whose email is never verified are deleted automatically after 7 days.
+      # For security, the API key is rotated the first time the account owner signs in
+      # to the GrowSurf dashboard. Some actions (such as emailing participants)
+      # additionally require GrowSurf to verify the team first. By creating an account
+      # you agree, on behalf of the account holder, to GrowSurf's [Terms of
+      # Service](https://growsurf.com/terms) and [Privacy
+      # Policy](https://growsurf.com/privacy).
       #
       # @overload create(email:, company: nil, first_name: nil, last_name: nil, request_options: {})
       #

data/lib/growsurf_ruby/resources/campaign/commission.rb

@@ -5,7 +5,7 @@ module GrowsurfRuby
     class Campaign
       # Affiliate transaction, commission, and payout operations.
       class Commission
-        # Removes a pending participant commission.
+        # **Affiliate programs only.** Removes a pending participant commission.
         #
         # @overload delete(commission_id, id:, request_options: {})
         #
@@ -32,7 +32,8 @@ module GrowsurfRuby
           )
         end
 
-        # Approves a pending participant commission so it can become eligible for payout.
+        # **Affiliate programs only.** Approves a pending participant commission so it can
+        # become eligible for payout.
         #
         # @overload approve(commission_id, id:, request_options: {})
         #

data/lib/growsurf_ruby/resources/campaign/design.rb

@@ -5,12 +5,11 @@ module GrowsurfRuby
     class Campaign
       class Design
         # Retrieves a program's design configuration — the same surface as the dashboard
-        # Program Editor's **Design** tab (window layout, header, share channels, signup
-        # form, portal/landing pages, theme styling, and summary/status sections).
-        #
-        # This is a large, deeply nested object whose available fields depend on the
-        # program type; the response includes every field and its current value, which
-        # is the same shape you send back on update.
+        # Program Editor's **Design** tab: the GrowSurf window layout, header, share
+        # channels + invite, signup form, portal/landing pages, theme styling, and the
+        # referral/affiliate summary + status sections. This is a large object whose
+        # available fields depend on the program type; the response includes every field
+        # and its current value, which is the same shape you send back on `PATCH`.
         #
         # @overload retrieve(id, request_options: {})
         #
@@ -31,11 +30,8 @@ module GrowsurfRuby
         # Updates a program's design configuration. Only the fields you send are changed;
         # anything you leave out is untouched (arrays such as `signup.fields` replace
         # wholesale). Unknown fields, fields not available for the program type, and
-        # invalid values return a `400`.
-        #
-        # The request body is a partial {CampaignDesign} object. To see the full object
-        # with every field and its current value, `GET` this resource, then `PATCH` back
-        # only the fields you want to change.
+        # invalid values return a `400`. Landing-page custom code and JavaScript are not
+        # editable via the API.
         #
         # @overload update(id, body, request_options: {})
         #

data/lib/growsurf_ruby/resources/campaign/emails.rb

@@ -5,11 +5,10 @@ module GrowsurfRuby
     class Campaign
       class Emails
         # Retrieves a program's email configuration — the same surface as the dashboard
-        # Program Editor's **Emails** tab (per-email templates plus sender, contact, and
-        # design settings).
-        #
-        # To see the full object with every field and its current value, `GET` this
-        # resource, then `PATCH` back only the fields you want to change.
+        # Program Editor's **Emails** tab. Returns each editable email template
+        # (`subject`, `preheader`, `body`, `isEnabled`) plus the `settings` block (sender,
+        # contact, and design). The set of email templates returned depends on the program
+        # type (referral vs affiliate).
         #
         # @overload retrieve(id, request_options: {})
         #
@@ -28,12 +27,11 @@ module GrowsurfRuby
         end
 
         # Updates a program's email configuration. Only the fields you send are changed;
-        # anything you leave out is untouched. Unknown fields and invalid values return a
-        # `400`.
-        #
-        # The request body is a partial {CampaignEmails} object. To see the full object
-        # with every field and its current value, `GET` this resource, then `PATCH` back
-        # only the fields you want to change.
+        # omitted fields are left untouched. You may only write the email templates the
+        # dashboard exposes for the program type — writing a template that is not
+        # available for the program type returns a `400`. Some fields are read-only
+        # (`settings.sender.fromEmail`, whose custom value requires dashboard domain
+        # verification).
         #
         # @overload update(id, body, request_options: {})
         #

data/lib/growsurf_ruby/resources/campaign/installation.rb

@@ -5,12 +5,9 @@ module GrowsurfRuby
     class Campaign
       class Installation
         # Retrieves a program's installation configuration — the same surface as the
-        # dashboard Program Editor's **Installation** tab (signup and mobile SDK
-        # installation settings).
-        #
-        # This is a nested object whose available fields depend on the program type. To
-        # see the full object with every field and its current value, `GET` this
-        # resource, then `PATCH` back only the fields you want to change.
+        # dashboard Program Editor's **Installation** tab (plus the Mobile SDK settings).
+        # Includes the referral trigger (referral programs only), signup tracking method,
+        # share URL and whitelist, custom-form signup settings, and mobile SDK settings.
         #
         # @overload retrieve(id, request_options: {})
         #
@@ -29,12 +26,11 @@ module GrowsurfRuby
         end
 
         # Updates a program's installation configuration. Only the fields you send are
-        # changed; anything you leave out is untouched. Unknown fields, fields not
-        # available for the program type, and invalid values return a `400`.
-        #
-        # The request body is a partial {CampaignInstallation} object. To see the full
-        # object with every field and its current value, `GET` this resource, then
-        # `PATCH` back only the fields you want to change.
+        # changed; omitted fields are left untouched. `referralTrigger` is only available
+        # for referral programs. `mobile.publicKey` is read-only; if no key exists yet,
+        # enabling `mobile.isEnabled` creates one. Changing `shareUrl` re-resolves its
+        # redirect destinations, which may take a moment to complete. URLs must include an
+        # explicit `http://` or `https://` scheme.
         #
         # @overload update(id, body, request_options: {})
         #

data/lib/growsurf_ruby/resources/campaign/options.rb

@@ -4,12 +4,11 @@ module GrowsurfRuby
   module Resources
     class Campaign
       class Options
-        # Retrieves a program's options configuration — the same surface as the dashboard
-        # Program Editor's **Options** tab (fraud/reCAPTCHA, tax documentation,
-        # notification emails, and other program settings).
-        #
-        # To see the full object with every field and its current value, `GET` this
-        # resource, then `PATCH` back only the fields you want to change.
+        # Retrieves a program's options — the same surface as the dashboard Program
+        # Editor's **Options** tab. Includes reward/fraud approval, anti-fraud lists +
+        # toggles, referral cookie/credit windows, reCAPTCHA, payout threshold + tax
+        # settings (affiliate only), and notification-email settings.
+        # `fraud.recaptcha.secretKey` is never returned.
         #
         # @overload retrieve(id, request_options: {})
         #
@@ -27,13 +26,12 @@ module GrowsurfRuby
           )
         end
 
-        # Updates a program's options configuration. Only the fields you send are changed;
-        # anything you leave out is untouched. Unknown fields and invalid values return a
-        # `400`.
-        #
-        # The request body is a partial {CampaignOptions} object. To see the full object
-        # with every field and its current value, `GET` this resource, then `PATCH` back
-        # only the fields you want to change.
+        # Updates a program's options. Only the fields you send are changed. Some fields
+        # are program-type specific (`requireManualRewardApproval`/`autoFulfillRewards`
+        # are referral-only; `payoutThreshold`/`taxDocumentation` are affiliate-only, and
+        # affiliate programs require `requireParticipantAuth: true`).
+        # `fraud.recaptcha.secretKey` is write-only. `referralCreditWindowDays: null`
+        # means "never expires".
         #
         # @overload update(id, body, request_options: {})
         #

data/lib/growsurf_ruby/resources/campaign/participant.rb

@@ -110,12 +110,12 @@ module GrowsurfRuby
         # {GrowsurfRuby::Models::Campaign::ParticipantBulkDeleteParams} for more details.
         #
         # Deletes a list of participants from a program in one request. Each entry in
-        # `participants` is a GrowSurf participant ID or an email address (mixed lists
-        # are allowed). Up to `200` entries per request — chunk larger lists across
-        # multiple calls. The response reports a per-row `status` for every submitted
-        # entry, so a `200` can include rows that were `NOT_FOUND` or failed. Deletion
-        # is permanent and removes the participants' referrals, rewards, commissions,
-        # and payout records.
+        # `participants` is a GrowSurf participant ID or an email address (mixed lists are
+        # allowed). Up to `200` entries per request — chunk larger lists across multiple
+        # calls. The response reports a per-row `status` for every submitted entry, so a
+        # `200` can include rows that were `NOT_FOUND` or failed. Deletion is permanent
+        # and removes the participants' referrals, rewards, commissions, and payout
+        # records.
         #
         # @overload bulk_delete(id, participants:, request_options: {})
         #
@@ -183,7 +183,8 @@ module GrowsurfRuby
           )
         end
 
-        # Retrieves a paged list of commissions earned by a participant.
+        # **Affiliate programs only.** Retrieves a paged list of commissions earned by a
+        # participant.
         #
         # @overload list_commissions(participant_id_or_email, id:, limit: nil, next_id: nil, status: nil, request_options: {})
         #
@@ -218,7 +219,8 @@ module GrowsurfRuby
           )
         end
 
-        # Retrieves a paged list of payouts that belong to a participant.
+        # **Affiliate programs only.** Retrieves a paged list of payouts that belong to a
+        # participant.
         #
         # @overload list_payouts(participant_id_or_email, id:, limit: nil, next_id: nil, status: nil, request_options: {})
         #
@@ -339,15 +341,12 @@ module GrowsurfRuby
           )
         end
 
-        # Records a sale made by a referred customer and generates affiliate commissions
-        # for their referrer when applicable.
-        #
-        # At least one transaction identifier is required: one of +external_id+,
-        # +transaction_id+, +order_id+, +payment_id+, +invoice_id+, +payment_intent_id+,
-        # or +charge_id+. +customer_id+ and +subscription_id+ do not count, since they
-        # identify the customer or subscription rather than the specific transaction.
-        # Without an identifier, resending the same sale creates a duplicate commission
-        # and double-pays the referrer; the server rejects such requests with HTTP 400.
+        # **Affiliate programs only.** Records a sale made by a referred customer and
+        # generates affiliate commissions for their referrer when applicable. Requires at
+        # least one transaction identifier (externalId, transactionId, orderId, paymentId,
+        # invoiceId, paymentIntentId, or chargeId) so repeated requests can be
+        # de-duplicated — without one, a resent sale would create a second commission.
+        # Reuse the same identifier(s) when refunding.
         #
         # @overload record_transaction(participant_id_or_email, id:, currency:, gross_amount:, amount_cash_net: nil, amount_paid: nil, charge_id: nil, customer_id: nil, description: nil, external_id: nil, invoice_id: nil, invoice_subtotal_excluding_tax: nil, invoice_total: nil, invoice_total_excluding_tax: nil, net_amount: nil, order_id: nil, paid_at: nil, payment_id: nil, payment_intent_id: nil, subscription_id: nil, tax_amount: nil, total_tax_amount: nil, total_tax_amounts: nil, total_taxes: nil, transaction_id: nil, request_options: {})
         #
@@ -421,9 +420,12 @@ module GrowsurfRuby
           )
         end
 
-        # Records an amendment (refund, partial refund, refund cancellation, or
-        # chargeback) against a previously recorded transaction and reverses or adjusts
-        # the referrer's commission.
+        # **Affiliate programs only.** Records an amendment (refund, partial refund,
+        # refund cancellation, or chargeback) against a previously recorded transaction
+        # and reverses or adjusts the referrer's commission. The inverse of Record
+        # Affiliate Transaction. Identify the original transaction with the same
+        # identifier(s) you sent when recording it. Commissions already paid out to the
+        # affiliate are not clawed back; the amendment is recorded for tax reporting only.
         #
         # @overload refund_transaction(participant_id_or_email, id:, amendment_type: nil, amount: nil, amount_refunded: nil, charge_id: nil, currency: nil, description: nil, external_id: nil, invoice_id: nil, order_id: nil, payment_id: nil, payment_intent_id: nil, refund_amount: nil, refund_id: nil, refund_status: nil, transaction_id: nil, request_options: {})
         #
@@ -482,7 +484,7 @@ module GrowsurfRuby
         end
 
         # Sends email invites on behalf of a participant to a list of email addresses.
-        # Sending invites via the API requires a verified custom email domain on the
+        # Sending invites via the API requires a **verified custom email domain** on the
         # program; the request fails until one is verified.
         #
         # @overload send_invites(participant_id_or_email, id:, email_addresses:, message_text:, subject_text:, request_options: {})
@@ -522,7 +524,10 @@ module GrowsurfRuby
         # details.
         #
         # Triggers referral credit for an existing referred participant by GrowSurf
-        # participant ID or email address.
+        # participant ID or email address. Optionally pass `delayInDays` to hold the
+        # credit for a number of days before it is awarded (for example, to cover your own
+        # refund window). A delayed trigger can be cancelled before it is awarded with the
+        # Cancel delayed referral trigger request (DELETE on this same path).
         #
         # @overload trigger_referral(participant_id_or_email, id:, delay_in_days: nil, request_options: {})
         #
@@ -552,8 +557,11 @@ module GrowsurfRuby
           )
         end
 
-        # Cancels a pending delayed referral trigger for an existing referred participant
-        # by GrowSurf participant ID or email address.
+        # Cancels a pending delayed referral trigger for a participant (the companion to a
+        # delayed Trigger referral request). Use this to undo a scheduled referral credit
+        # before it is awarded, for example when a refund occurs inside your refund
+        # window. If the participant has no pending delayed trigger, `success` is returned
+        # as `false`.
         #
         # @overload cancel_delayed_referral(participant_id_or_email, id:, request_options: {})
         #
@@ -580,15 +588,14 @@ module GrowsurfRuby
           )
         end
 
-        # Sends an email to a participant. Provide EITHER `email_type` to trigger one of the
-        # program's configured email templates, OR `subject` + `body` for a free-form email.
-        # Free-form emails are sent with the same compliance handling (company name,
-        # postal address, and an unsubscribe link are added automatically, and unsubscribed
-        # participants are suppressed). Sending requires the team to be verified by
-        # GrowSurf. Requires a verified custom email domain on the program (set up
-        # in Campaign Editor > 3. Emails > Email Settings). Returns `400` until one is
-        # verified.
-        # The email is accepted for delivery.
+        # Sends an email to a participant. Provide EITHER `emailType` to trigger one of
+        # the program's configured email templates, OR `subject` + `body` for a free-form
+        # email. Free-form emails are sent with the same compliance handling (company
+        # name, postal address, and an unsubscribe link are added automatically, and
+        # unsubscribed participants are suppressed). Sending requires the team to be
+        # verified by GrowSurf. Requires a **verified custom email domain** on the program
+        # (which can be completed in *Campaign Editor > 3. Emails > Email Settings*).
+        # Returns `400` until one is verified. The email is accepted for delivery.
         #
         # @overload email(participant_id_or_email, id:, body: nil, email_type: nil, preheader: nil, subject: nil, request_options: {})
         #
@@ -624,7 +631,8 @@ module GrowsurfRuby
           )
         end
 
-        # Returns a participant's activity logs, most recent first (offset/limit paginated).
+        # Returns a participant's activity logs, most recent first (offset/limit
+        # paginated).
         #
         # @overload list_activity_logs(participant_id_or_email, id:, limit: nil, offset: nil, request_options: {})
         #
@@ -662,8 +670,9 @@ module GrowsurfRuby
         # details.
         #
         # Retrieves analytics for a single participant — all-time engagement counters,
-        # leaderboard ranks, and per-channel share counts (plus affiliate money metrics for
-        # affiliate programs). Useful for segmenting and re-engaging participants.
+        # leaderboard ranks, and per-channel share counts (plus affiliate money metrics
+        # for affiliate programs). Useful for segmenting and re-engaging participants.
+        # Pass `include=series` to also get this participant's own activity over time.
         #
         # @overload retrieve_analytics(participant_id_or_email, id:, days: nil, end_date: nil, include: nil, interval: nil, start_date: nil, request_options: {})
         #

data/lib/growsurf_ruby/resources/campaign/reward.rb

@@ -33,8 +33,9 @@ module GrowsurfRuby
           )
         end
 
-        # Approves a manually approved reward earned by a participant. Requires
-        # `reward:write`. Passing `fulfill: true` also requires `reward:fulfill`.
+        # Approves a manually approved reward earned by a participant. This requires
+        # `reward:write`. When the request also sets `fulfill` to `true`, it additionally
+        # requires `reward:fulfill`.
         #
         # @overload approve(reward_id, id:, fulfill: nil, request_options: {})
         #
@@ -64,7 +65,7 @@ module GrowsurfRuby
           )
         end
 
-        # Marks an approved participant reward as fulfilled. Requires `reward:fulfill`.
+        # Marks an approved participant reward as fulfilled.
         #
         # @overload fulfill(reward_id, id:, request_options: {})
         #

data/lib/growsurf_ruby/resources/campaign/rewards.rb

@@ -4,7 +4,9 @@ module GrowsurfRuby
   module Resources
     class Campaign
       class Rewards
-        # Retrieves the rewards configured for a program.
+        # Retrieves the list of a program's configured rewards (`CampaignReward`s) — the
+        # same set embedded in the `rewards` array of the campaign response. Delete a
+        # reward with `DELETE /campaign/{id}/reward-configs/{campaignRewardId}`.
         #
         # @overload list(id, request_options: {})
         #
@@ -22,8 +24,11 @@ module GrowsurfRuby
           )
         end
 
-        # Creates a reward for a program. The reward `type` must be compatible with the
-        # program type.
+        # Creates a new campaign reward (`CampaignReward`) with a GrowSurf-assigned ID.
+        # 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.
         #
         # @overload create(id, type:, commission_structure: nil, conversions_required: nil, coupon_code: nil, description: nil, image_url: nil, is_unlimited: nil, is_visible: nil, limit: nil, limit_duration: nil, metadata: nil, next_milestone_prefix: nil, next_milestone_suffix: nil, number_of_winners: nil, order: nil, referral_coupon_code: nil, referral_description: nil, referred_reward_upfront: nil, referred_value: nil, title: nil, value: nil, request_options: {})
         #
@@ -87,8 +92,11 @@ module GrowsurfRuby
           )
         end
 
-        # Updates an existing campaign reward. Only the fields you send are changed;
-        # `type` is immutable and must not be supplied.
+        # Updates an existing campaign reward (`CampaignReward`). The reward `type` is
+        # 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.
         #
         # @overload update(campaign_reward_id, id:, commission_structure: nil, conversions_required: nil, coupon_code: nil, description: nil, image_url: nil, is_unlimited: nil, is_visible: nil, limit: nil, limit_duration: nil, metadata: nil, next_milestone_prefix: nil, next_milestone_suffix: nil, number_of_winners: nil, order: nil, referral_coupon_code: nil, referral_description: nil, referred_reward_upfront: nil, referred_value: nil, title: nil, value: nil, request_options: {})
         #
@@ -156,7 +164,11 @@ module GrowsurfRuby
           )
         end
 
-        # Deletes a campaign reward.
+        # Deletes a campaign reward (`CampaignReward`). The reward is deactivated, removed
+        # from the program's reward set, and any connected upfront-discount coupons are
+        # cleaned up. If campaign copy still references any of the reward's metadata keys
+        # via `{{campaignReward[…]}}` tokens, the delete returns a `409` listing the
+        # referencing fields — update those fields first.
         #
         # @overload delete(campaign_reward_id, id:, request_options: {})
         #

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 program 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: {})
       #
@@ -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: {})
       #
@@ -210,7 +209,8 @@ module GrowsurfRuby
         )
       end
 
-      # Retrieves a paged list of all participant commissions in an affiliate program.
+      # **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 +301,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: {})
       #
@@ -381,7 +382,9 @@ module GrowsurfRuby
       # 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, or derived rates — useful for detecting trends over time.
       #
       # @overload retrieve_analytics(id, days: nil, end_date: nil, include: nil, interval: nil, start_date: nil, request_options: {})
       #

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.2.1"
 end

data/rbi/growsurf_ruby/resources/account.rbi

@@ -3,6 +3,20 @@
 module GrowsurfRuby
   module Resources
     class Account
+      # Creates a new GrowSurf account. This is the only endpoint that does not require
+      # an API key. The response includes an API key for the new account, shown once in
+      # the response. The key is locked until the team owner's email address is
+      # verified: authenticated program and resource endpoints return a `403` with error
+      # code `EMAIL_NOT_VERIFIED_ERROR` until then (resend the email via `POST
+      # /team/owner/verification-email`, then retry). A welcome email is sent to the
+      # address with the verification link and a set-password link for dashboard access.
+      # Accounts whose email is never verified are deleted automatically after 7 days.
+      # For security, the API key is rotated the first time the account owner signs in
+      # to the GrowSurf dashboard. Some actions (such as emailing participants)
+      # additionally require GrowSurf to verify the team first. By creating an account
+      # you agree, on behalf of the account holder, to GrowSurf's [Terms of
+      # Service](https://growsurf.com/terms) and [Privacy
+      # Policy](https://growsurf.com/privacy).
       sig do
         params(
           email: String,

data/rbi/growsurf_ruby/resources/campaign/commission.rbi

@@ -5,7 +5,7 @@ module GrowsurfRuby
     class Campaign
       # Affiliate transaction, commission, and payout operations.
       class Commission
-        # Removes a pending participant commission.
+        # **Affiliate programs only.** Removes a pending participant commission.
         sig do
           params(
             commission_id: String,
@@ -22,7 +22,8 @@ module GrowsurfRuby
         )
         end
 
-        # Approves a pending participant commission so it can become eligible for payout.
+        # **Affiliate programs only.** Approves a pending participant commission so it can
+        # become eligible for payout.
         sig do
           params(
             commission_id: String,

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

@@ -5,9 +5,11 @@ module GrowsurfRuby
     class Campaign
       class Design
         # Retrieves a program's design configuration — the same surface as the dashboard
-        # Program Editor's **Design** tab. This is a large, deeply nested object whose
+        # Program Editor's **Design** tab: the GrowSurf window layout, header, share
+        # channels + invite, signup form, portal/landing pages, theme styling, and the
+        # referral/affiliate summary + status sections. This is a large object whose
         # available fields depend on the program type; the response includes every field
-        # and its current value, which is the same shape you send back on update.
+        # and its current value, which is the same shape you send back on `PATCH`.
         sig do
           params(
             id: String,
@@ -23,9 +25,9 @@ module GrowsurfRuby
 
         # Updates a program's design configuration. Only the fields you send are changed;
         # anything you leave out is untouched (arrays such as `signup.fields` replace
-        # wholesale). The request body is a partial design object. To see the full object
-        # with every field and its current value, `GET` this resource, then `PATCH` back
-        # only the fields you want to change.
+        # wholesale). Unknown fields, fields not available for the program type, and
+        # invalid values return a `400`. Landing-page custom code and JavaScript are not
+        # editable via the API.
         sig do
           params(
             id: String,

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

@@ -5,9 +5,10 @@ module GrowsurfRuby
     class Campaign
       class Emails
         # Retrieves a program's email configuration — the same surface as the dashboard
-        # Program Editor's **Emails** tab. To see the full object with every field and its
-        # current value, `GET` this resource, then `PATCH` back only the fields you want to
-        # change.
+        # Program Editor's **Emails** tab. Returns each editable email template
+        # (`subject`, `preheader`, `body`, `isEnabled`) plus the `settings` block (sender,
+        # contact, and design). The set of email templates returned depends on the program
+        # type (referral vs affiliate).
         sig do
           params(
             id: String,
@@ -22,9 +23,11 @@ module GrowsurfRuby
         end
 
         # Updates a program's email configuration. Only the fields you send are changed;
-        # anything you leave out is untouched. The request body is a partial email
-        # configuration object. To see the full object with every field and its current
-        # value, `GET` this resource, then `PATCH` back only the fields you want to change.
+        # omitted fields are left untouched. You may only write the email templates the
+        # dashboard exposes for the program type — writing a template that is not
+        # available for the program type returns a `400`. Some fields are read-only
+        # (`settings.sender.fromEmail`, whose custom value requires dashboard domain
+        # verification).
         sig do
           params(
             id: String,

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

@@ -5,10 +5,9 @@ module GrowsurfRuby
     class Campaign
       class Installation
         # Retrieves a program's installation configuration — the same surface as the
-        # dashboard Program Editor's **Installation** tab. This is a nested object whose
-        # available fields depend on the program type. To see the full object with every
-        # field and its current value, `GET` this resource, then `PATCH` back only the
-        # fields you want to change.
+        # dashboard Program Editor's **Installation** tab (plus the Mobile SDK settings).
+        # Includes the referral trigger (referral programs only), signup tracking method,
+        # share URL and whitelist, custom-form signup settings, and mobile SDK settings.
         sig do
           params(
             id: String,
@@ -23,10 +22,11 @@ module GrowsurfRuby
         end
 
         # Updates a program's installation configuration. Only the fields you send are
-        # changed; anything you leave out is untouched. The request body is a partial
-        # installation configuration object. To see the full object with every field and
-        # its current value, `GET` this resource, then `PATCH` back only the fields you
-        # want to change.
+        # changed; omitted fields are left untouched. `referralTrigger` is only available
+        # for referral programs. `mobile.publicKey` is read-only; if no key exists yet,
+        # enabling `mobile.isEnabled` creates one. Changing `shareUrl` re-resolves its
+        # redirect destinations, which may take a moment to complete. URLs must include an
+        # explicit `http://` or `https://` scheme.
         sig do
           params(
             id: String,

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

@@ -4,10 +4,11 @@ module GrowsurfRuby
   module Resources
     class Campaign
       class Options
-        # Retrieves a program's options configuration — the same surface as the dashboard
-        # Program Editor's **Options** tab. To see the full object with every field and its
-        # current value, `GET` this resource, then `PATCH` back only the fields you want to
-        # change.
+        # Retrieves a program's options — the same surface as the dashboard Program
+        # Editor's **Options** tab. Includes reward/fraud approval, anti-fraud lists +
+        # toggles, referral cookie/credit windows, reCAPTCHA, payout threshold + tax
+        # settings (affiliate only), and notification-email settings.
+        # `fraud.recaptcha.secretKey` is never returned.
         sig do
           params(
             id: String,
@@ -21,10 +22,12 @@ module GrowsurfRuby
         )
         end
 
-        # Updates a program's options configuration. Only the fields you send are changed;
-        # anything you leave out is untouched. The request body is a partial options
-        # configuration object. To see the full object with every field and its current
-        # value, `GET` this resource, then `PATCH` back only the fields you want to change.
+        # Updates a program's options. Only the fields you send are changed. Some fields
+        # are program-type specific (`requireManualRewardApproval`/`autoFulfillRewards`
+        # are referral-only; `payoutThreshold`/`taxDocumentation` are affiliate-only, and
+        # affiliate programs require `requireParticipantAuth: true`).
+        # `fraud.recaptcha.secretKey` is write-only. `referralCreditWindowDays: null`
+        # means "never expires".
         sig do
           params(
             id: String,

data/rbi/growsurf_ruby/resources/campaign/participant.rbi

@@ -88,12 +88,12 @@ module GrowsurfRuby
         end
 
         # Deletes a list of participants from a program in one request. Each entry in
-        # `participants` is a GrowSurf participant ID or an email address (mixed lists
-        # are allowed). Up to `200` entries per request — chunk larger lists across
-        # multiple calls. The response reports a per-row `status` for every submitted
-        # entry, so a `200` can include rows that were `NOT_FOUND` or failed. Deletion
-        # is permanent and removes the participants' referrals, rewards, commissions,
-        # and payout records.
+        # `participants` is a GrowSurf participant ID or an email address (mixed lists are
+        # allowed). Up to `200` entries per request — chunk larger lists across multiple
+        # calls. The response reports a per-row `status` for every submitted entry, so a
+        # `200` can include rows that were `NOT_FOUND` or failed. Deletion is permanent
+        # and removes the participants' referrals, rewards, commissions, and payout
+        # records.
         sig do
           params(
             id: String,
@@ -156,7 +156,8 @@ module GrowsurfRuby
         )
         end
 
-        # Retrieves a paged list of commissions earned by a participant.
+        # **Affiliate programs only.** Retrieves a paged list of commissions earned by a
+        # participant.
         sig do
           params(
             participant_id_or_email: String,
@@ -183,7 +184,8 @@ module GrowsurfRuby
         )
         end
 
-        # Retrieves a paged list of payouts that belong to a participant.
+        # **Affiliate programs only.** Retrieves a paged list of payouts that belong to a
+        # participant.
         sig do
           params(
             participant_id_or_email: String,
@@ -280,15 +282,12 @@ module GrowsurfRuby
         )
         end
 
-        # Records a sale made by a referred customer and generates affiliate commissions
-        # for their referrer when applicable.
-        #
-        # At least one transaction identifier is required: one of +external_id+,
-        # +transaction_id+, +order_id+, +payment_id+, +invoice_id+, +payment_intent_id+,
-        # or +charge_id+. +customer_id+ and +subscription_id+ do not count, since they
-        # identify the customer or subscription rather than the specific transaction.
-        # Without an identifier, resending the same sale creates a duplicate commission
-        # and double-pays the referrer; the server rejects such requests with HTTP 400.
+        # **Affiliate programs only.** Records a sale made by a referred customer and
+        # generates affiliate commissions for their referrer when applicable. Requires at
+        # least one transaction identifier (externalId, transactionId, orderId, paymentId,
+        # invoiceId, paymentIntentId, or chargeId) so repeated requests can be
+        # de-duplicated — without one, a resent sale would create a second commission.
+        # Reuse the same identifier(s) when refunding.
         sig do
           params(
             participant_id_or_email: String,
@@ -376,9 +375,12 @@ module GrowsurfRuby
         )
         end
 
-        # Records an amendment (refund, partial refund, refund cancellation, or
-        # chargeback) against a previously recorded transaction and reverses or adjusts
-        # the referrer's commission.
+        # **Affiliate programs only.** Records an amendment (refund, partial refund,
+        # refund cancellation, or chargeback) against a previously recorded transaction
+        # and reverses or adjusts the referrer's commission. The inverse of Record
+        # Affiliate Transaction. Identify the original transaction with the same
+        # identifier(s) you sent when recording it. Commissions already paid out to the
+        # affiliate are not clawed back; the amendment is recorded for tax reporting only.
         sig do
           params(
             participant_id_or_email: String,
@@ -444,7 +446,7 @@ module GrowsurfRuby
         end
 
         # Sends email invites on behalf of a participant to a list of email addresses.
-        # Sending invites via the API requires a verified custom email domain on the
+        # Sending invites via the API requires a **verified custom email domain** on the
         # program; the request fails until one is verified.
         sig do
           params(
@@ -474,7 +476,10 @@ module GrowsurfRuby
         end
 
         # Triggers referral credit for an existing referred participant by GrowSurf
-        # participant ID or email address.
+        # participant ID or email address. Optionally pass `delayInDays` to hold the
+        # credit for a number of days before it is awarded (for example, to cover your own
+        # refund window). A delayed trigger can be cancelled before it is awarded with the
+        # Cancel delayed referral trigger request (DELETE on this same path).
         sig do
           params(
             participant_id_or_email: String,
@@ -500,8 +505,11 @@ module GrowsurfRuby
         )
         end
 
-        # Cancels a pending delayed referral trigger for an existing referred participant
-        # by GrowSurf participant ID or email address.
+        # Cancels a pending delayed referral trigger for a participant (the companion to a
+        # delayed Trigger referral request). Use this to undo a scheduled referral credit
+        # before it is awarded, for example when a refund occurs inside your refund
+        # window. If the participant has no pending delayed trigger, `success` is returned
+        # as `false`.
         sig do
           params(
             participant_id_or_email: String,
@@ -520,15 +528,14 @@ module GrowsurfRuby
         )
         end
 
-        # Sends an email to a participant. Provide EITHER `email_type` to trigger one of the
-        # program's configured email templates, OR `subject` + `body` for a free-form email.
-        # Free-form emails are sent with the same compliance handling (company name,
-        # postal address, and an unsubscribe link are added automatically, and unsubscribed
-        # participants are suppressed). Sending requires the team to be verified by
-        # GrowSurf. Requires a verified custom email domain on the program (set up
-        # in Campaign Editor > 3. Emails > Email Settings). Returns `400` until one is
-        # verified.
-        # The email is accepted for delivery.
+        # Sends an email to a participant. Provide EITHER `emailType` to trigger one of
+        # the program's configured email templates, OR `subject` + `body` for a free-form
+        # email. Free-form emails are sent with the same compliance handling (company
+        # name, postal address, and an unsubscribe link are added automatically, and
+        # unsubscribed participants are suppressed). Sending requires the team to be
+        # verified by GrowSurf. Requires a **verified custom email domain** on the program
+        # (which can be completed in *Campaign Editor > 3. Emails > Email Settings*).
+        # Returns `400` until one is verified. The email is accepted for delivery.
         sig do
           params(
             participant_id_or_email: String,
@@ -569,7 +576,8 @@ module GrowsurfRuby
         )
         end
 
-        # Returns a participant's activity logs, most recent first (offset/limit paginated).
+        # Returns a participant's activity logs, most recent first (offset/limit
+        # paginated).
         sig do
           params(
             participant_id_or_email: String,
@@ -595,8 +603,9 @@ module GrowsurfRuby
         end
 
         # Retrieves analytics for a single participant — all-time engagement counters,
-        # leaderboard ranks, and per-channel share counts (plus affiliate money metrics for
-        # affiliate programs). Useful for segmenting and re-engaging participants.
+        # leaderboard ranks, and per-channel share counts (plus affiliate money metrics
+        # for affiliate programs). Useful for segmenting and re-engaging participants.
+        # Pass `include=series` to also get this participant's own activity over time.
         sig do
           params(
             participant_id_or_email: String,

data/rbi/growsurf_ruby/resources/campaign/reward.rbi

@@ -23,8 +23,9 @@ module GrowsurfRuby
         )
         end
 
-        # Approves a manually approved reward earned by a participant. Requires
-        # `reward:write`. Passing `fulfill: true` also requires `reward:fulfill`.
+        # Approves a manually approved reward earned by a participant. This requires
+        # `reward:write`. When the request also sets `fulfill` to `true`, it additionally
+        # requires `reward:fulfill`.
         sig do
           params(
             reward_id: String,
@@ -44,7 +45,7 @@ module GrowsurfRuby
         )
         end
 
-        # Marks an approved participant reward as fulfilled. Requires `reward:fulfill`.
+        # Marks an approved participant reward as fulfilled.
         sig do
           params(
             reward_id: String,

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

@@ -4,7 +4,9 @@ module GrowsurfRuby
   module Resources
     class Campaign
       class Rewards
-        # Retrieves the rewards configured for a program.
+        # Retrieves the list of a program's configured rewards (`CampaignReward`s) — the
+        # same set embedded in the `rewards` array of the campaign response. Delete a
+        # reward with `DELETE /campaign/{id}/reward-configs/{campaignRewardId}`.
         sig do
           params(
             id: String,
@@ -18,8 +20,11 @@ module GrowsurfRuby
         )
         end
 
-        # Creates a reward for a program. The reward `type` must be compatible with the
-        # program type.
+        # Creates a new campaign reward (`CampaignReward`) with a GrowSurf-assigned ID.
+        # 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.
         sig do
           params(
             id: String,
@@ -112,8 +117,11 @@ module GrowsurfRuby
         )
         end
 
-        # Updates an existing campaign reward. Only the fields you send are changed; `type`
-        # is immutable and must not be supplied.
+        # Updates an existing campaign reward (`CampaignReward`). The reward `type` is
+        # 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.
         sig do
           params(
             campaign_reward_id: String,
@@ -205,7 +213,11 @@ module GrowsurfRuby
         )
         end
 
-        # Deletes a campaign reward.
+        # Deletes a campaign reward (`CampaignReward`). The reward is deactivated, removed
+        # from the program's reward set, and any connected upfront-discount coupons are
+        # cleaned up. If campaign copy still references any of the reward's metadata keys
+        # via `{{campaignReward[…]}}` tokens, the delete returns a `409` listing the
+        # referencing fields — update those fields first.
         sig do
           params(
             campaign_reward_id: String,

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 program 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,
@@ -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,
@@ -179,7 +179,8 @@ module GrowsurfRuby
       )
       end
 
-      # Retrieves a paged list of all participant commissions in an affiliate program.
+      # **Affiliate programs only.** Retrieves a paged list of all participant
+      # commissions in an affiliate program.
       sig do
         params(
           id: String,
@@ -249,7 +250,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 +315,9 @@ module GrowsurfRuby
       )
       end
 
-      # 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, or derived rates — useful for detecting trends over time.
       sig do
         params(
           id: String,

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: growsurf-ruby
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Growsurf
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-13 00:00:00.000000000 Z
+date: 2026-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cgi