growsurf-python 1.2.0__py3-none-any.whl → 1.2.1__py3-none-any.whl

growsurf/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "growsurf"
-__version__ = "1.2.0"  # x-release-please-version
+__version__ = "1.2.1"  # x-release-please-version

growsurf/resources/account.py

@@ -46,11 +46,21 @@ class AccountResource(SyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> CreateAccountResponse:
-        """Create a GrowSurf account and return its one-time API key.
-
-        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. Accounts whose
-        email is never verified are deleted automatically after 7 days.
+        """
+        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).
 
         Args:
           email: The email address for the new GrowSurf account. Personal emails and disposable email addresses are not accepted.
@@ -116,11 +126,21 @@ class AsyncAccountResource(AsyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> CreateAccountResponse:
-        """Create a GrowSurf account and return its one-time API key.
-
-        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. Accounts whose
-        email is never verified are deleted automatically after 7 days.
+        """
+        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).
 
         Args:
           email: The email address for the new GrowSurf account. Personal emails and disposable email addresses are not accepted.

growsurf/resources/campaign/campaign.py

@@ -196,9 +196,8 @@ class CampaignResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> Campaign:
         """
-        Creates a new program pre-populated with type-appropriate defaults, plus any
-        optional inline rewards. The new program is created in `DRAFT` status and owned
-        by the API key's bound team. Requires the team owner's verified email.
+        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.
 
         Args:
           type: The program type. Immutable after creation.
@@ -289,8 +288,8 @@ class CampaignResource(SyncAPIResource):
         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.
+        dedicated config sub-resources, not here. The program cannot be deleted via this
+        endpoint.
 
         Args:
           status: The requested program status. `IN_PROGRESS` publishes or resumes the program;
@@ -458,7 +457,8 @@ class CampaignResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ParticipantCommissionList:
         """
-        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.
 
         Args:
           limit: Number of results to return. Maximum 100.
@@ -628,7 +628,8 @@ class CampaignResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ParticipantPayoutList:
         """
-        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.
 
         Args:
           limit: Number of results to return. Maximum 100.
@@ -762,10 +763,9 @@ class CampaignResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> CampaignRetrieveAnalyticsResponse:
         """
-        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.
+        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.
 
         Args:
           days: Last number of days to retrieve analytics for. Defaults to 365. Maximum 1825.
@@ -898,9 +898,8 @@ class AsyncCampaignResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> Campaign:
         """
-        Creates a new program pre-populated with type-appropriate defaults, plus any
-        optional inline rewards. The new program is created in `DRAFT` status and owned
-        by the API key's bound team. Requires the team owner's verified email.
+        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.
 
         Args:
           type: The program type. Immutable after creation.
@@ -991,8 +990,8 @@ class AsyncCampaignResource(AsyncAPIResource):
         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.
+        dedicated config sub-resources, not here. The program cannot be deleted via this
+        endpoint.
 
         Args:
           status: The requested program status. `IN_PROGRESS` publishes or resumes the program;
@@ -1160,7 +1159,8 @@ class AsyncCampaignResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ParticipantCommissionList:
         """
-        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.
 
         Args:
           limit: Number of results to return. Maximum 100.
@@ -1330,7 +1330,8 @@ class AsyncCampaignResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ParticipantPayoutList:
         """
-        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.
 
         Args:
           limit: Number of results to return. Maximum 100.
@@ -1464,10 +1465,9 @@ class AsyncCampaignResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> CampaignRetrieveAnalyticsResponse:
         """
-        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.
+        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.
 
         Args:
           days: Last number of days to retrieve analytics for. Defaults to 365. Maximum 1825.

growsurf/resources/campaign/commission.py

@@ -56,7 +56,7 @@ class CommissionResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> CommissionDeleteResponse:
         """
-        Removes a pending participant commission.
+        **Affiliate programs only.** Removes a pending participant commission.
 
         Args:
           extra_headers: Send extra headers
@@ -92,7 +92,8 @@ class CommissionResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> CommissionApproveResponse:
         """
-        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.
 
         Args:
           extra_headers: Send extra headers
@@ -151,7 +152,7 @@ class AsyncCommissionResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> CommissionDeleteResponse:
         """
-        Removes a pending participant commission.
+        **Affiliate programs only.** Removes a pending participant commission.
 
         Args:
           extra_headers: Send extra headers
@@ -187,7 +188,8 @@ class AsyncCommissionResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> CommissionApproveResponse:
         """
-        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.
 
         Args:
           extra_headers: Send extra headers

growsurf/resources/campaign/design.py

@@ -57,9 +57,11 @@ class DesignResource(SyncAPIResource):
     ) -> CampaignDesign:
         """
         Retrieves a program's design configuration — the same surface as the dashboard
-        Program Editor's **Design** tab. 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`.
+        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`.
 
         Args:
           extra_headers: Send extra headers
@@ -96,9 +98,8 @@ class DesignResource(SyncAPIResource):
         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`. To see the full `CampaignDesign` object with every
-        field and its current value, `GET` this resource first, 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.
 
         Args:
           body: A partial `CampaignDesign` object — only the fields you send are changed.
@@ -158,9 +159,11 @@ class AsyncDesignResource(AsyncAPIResource):
     ) -> CampaignDesign:
         """
         Retrieves a program's design configuration — the same surface as the dashboard
-        Program Editor's **Design** tab. 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`.
+        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`.
 
         Args:
           extra_headers: Send extra headers
@@ -197,9 +200,8 @@ class AsyncDesignResource(AsyncAPIResource):
         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`. To see the full `CampaignDesign` object with every
-        field and its current value, `GET` this resource first, 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.
 
         Args:
           body: A partial `CampaignDesign` object — only the fields you send are changed.

growsurf/resources/campaign/emails.py

@@ -56,10 +56,11 @@ class EmailsResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> CampaignEmails:
         """
-        Retrieves a program's emails configuration — the same surface as the dashboard
-        Program Editor's **Emails** tab. 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`.
+        Retrieves a program's email configuration — the same surface as the dashboard
+        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).
 
         Args:
           extra_headers: Send extra headers
@@ -95,12 +96,10 @@ class EmailsResource(SyncAPIResource):
         """
         Updates a program's email configuration. Only the fields you send are changed;
         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
+        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). To see the full `CampaignEmails` object with every field and its
-        current value, `GET` this resource first, then `PATCH` back only the fields you
-        want to change.
+        verification).
 
         Args:
           body: A partial `CampaignEmails` object — only the fields you send are changed.
@@ -159,10 +158,11 @@ class AsyncEmailsResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> CampaignEmails:
         """
-        Retrieves a program's emails configuration — the same surface as the dashboard
-        Program Editor's **Emails** tab. 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`.
+        Retrieves a program's email configuration — the same surface as the dashboard
+        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).
 
         Args:
           extra_headers: Send extra headers
@@ -198,12 +198,10 @@ class AsyncEmailsResource(AsyncAPIResource):
         """
         Updates a program's email configuration. Only the fields you send are changed;
         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
+        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). To see the full `CampaignEmails` object with every field and its
-        current value, `GET` this resource first, then `PATCH` back only the fields you
-        want to change.
+        verification).
 
         Args:
           body: A partial `CampaignEmails` object — only the fields you send are changed.

growsurf/resources/campaign/installation.py

@@ -56,10 +56,10 @@ class InstallationResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> CampaignInstallation:
         """
-        Retrieves a program's installation configuration — the same surface as the dashboard
-        Program Editor's **Installation** tab. 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`.
+        Retrieves a program's installation configuration — the same surface as the
+        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.
 
         Args:
           extra_headers: Send extra headers
@@ -95,10 +95,10 @@ class InstallationResource(SyncAPIResource):
         """
         Updates a program's installation configuration. Only the fields you send are
         changed; omitted fields are left untouched. `referralTrigger` is only available
-        for referral programs. `mobile.publicKey` is read-only (server-generated). URLs
-        must include an explicit `http://` or `https://` scheme. To see the full
-        `CampaignInstallation` object with every field and its current value, `GET` this
-        resource first, then `PATCH` back only the fields you want to change.
+        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.
 
         Args:
           body: A partial `CampaignInstallation` object — only the fields you send are changed.
@@ -157,10 +157,10 @@ class AsyncInstallationResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> CampaignInstallation:
         """
-        Retrieves a program's installation configuration — the same surface as the dashboard
-        Program Editor's **Installation** tab. 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`.
+        Retrieves a program's installation configuration — the same surface as the
+        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.
 
         Args:
           extra_headers: Send extra headers
@@ -196,10 +196,10 @@ class AsyncInstallationResource(AsyncAPIResource):
         """
         Updates a program's installation configuration. Only the fields you send are
         changed; omitted fields are left untouched. `referralTrigger` is only available
-        for referral programs. `mobile.publicKey` is read-only (server-generated). URLs
-        must include an explicit `http://` or `https://` scheme. To see the full
-        `CampaignInstallation` object with every field and its current value, `GET` this
-        resource first, then `PATCH` back only the fields you want to change.
+        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.
 
         Args:
           body: A partial `CampaignInstallation` object — only the fields you send are changed.

growsurf/resources/campaign/options.py

@@ -56,10 +56,11 @@ class OptionsResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> CampaignOptions:
         """
-        Retrieves a program's options configuration — the same surface as the dashboard
-        Program Editor's **Options** tab. 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`.
+        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.
 
         Args:
           extra_headers: Send extra headers
@@ -93,14 +94,12 @@ class OptionsResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> CampaignOptions:
         """
-        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
+        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". To see the full `CampaignOptions` object with every field and its
-        current value, `GET` this resource first, then `PATCH` back only the fields you
-        want to change.
+        `fraud.recaptcha.secretKey` is write-only. `referralCreditWindowDays: null`
+        means "never expires".
 
         Args:
           body: A partial `CampaignOptions` object — only the fields you send are changed.
@@ -159,10 +158,11 @@ class AsyncOptionsResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> CampaignOptions:
         """
-        Retrieves a program's options configuration — the same surface as the dashboard
-        Program Editor's **Options** tab. 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`.
+        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.
 
         Args:
           extra_headers: Send extra headers
@@ -196,14 +196,12 @@ class AsyncOptionsResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> CampaignOptions:
         """
-        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
+        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". To see the full `CampaignOptions` object with every field and its
-        current value, `GET` this resource first, then `PATCH` back only the fields you
-        want to change.
+        `fraud.recaptcha.secretKey` is write-only. `referralCreditWindowDays: null`
+        means "never expires".
 
         Args:
           body: A partial `CampaignOptions` object — only the fields you send are changed.

growsurf/resources/campaign/participant.py

@@ -244,15 +244,14 @@ class ParticipantResource(SyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ParticipantBulkDeleteResponse:
-        """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.
+        """
+        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.
 
         Args:
           participants: GrowSurf participant IDs and/or email addresses to delete. Mixed entries are
@@ -299,9 +298,8 @@ class ParticipantResource(SyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> Participant:
-        """Adds a new participant to the program.
-
-        If the email already exists, the existing
+        """
+        Adds a new participant to the program. If the email already exists, the existing
         participant is returned.
 
         Args:
@@ -366,7 +364,8 @@ class ParticipantResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ParticipantCommissionList:
         """
-        Retrieves a paged list of commissions earned by a participant.
+        **Affiliate programs only.** Retrieves a paged list of commissions earned by a
+        participant.
 
         Args:
           limit: Number of results to return. Maximum 100.
@@ -428,7 +427,8 @@ class ParticipantResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ParticipantPayoutList:
         """
-        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.
 
         Args:
           limit: Number of results to return. Maximum 100.
@@ -655,16 +655,12 @@ class ParticipantResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ParticipantRecordTransactionResponse:
         """
-        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.
 
         Args:
           extra_headers: Send extra headers
@@ -754,11 +750,12 @@ class ParticipantResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ParticipantRefundTransactionResponse:
         """
-        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.
-        Commissions already paid out are not clawed back; the amendment is recorded for
-        tax reporting only.
+        **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.
 
         Args:
           extra_headers: Send extra headers
@@ -824,8 +821,7 @@ class ParticipantResource(SyncAPIResource):
     ) -> ParticipantSendInvitesResponse:
         """
         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.
 
         Args:
@@ -878,7 +874,10 @@ class ParticipantResource(SyncAPIResource):
     ) -> ParticipantTriggerReferralResponse:
         """
         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).
 
         Args:
           delay_in_days: Number of whole days to hold referral credit before it is awarded. Useful for
@@ -929,8 +928,11 @@ class ParticipantResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ParticipantTriggerReferralResponse:
         """
-        Cancels a pending delayed referral trigger for a 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`.
 
         Args:
           extra_headers: Send extra headers
@@ -976,14 +978,14 @@ class ParticipantResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> EmailParticipantResponse:
         """
-        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.
 
         Args:
           email_type: The program email template to trigger (template mode). The valid values depend on
@@ -1115,9 +1117,9 @@ class ParticipantResource(SyncAPIResource):
     ) -> ParticipantAnalyticsResponse:
         """
         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. Pass
-        ``include=series`` to also get this participant's own activity over time.
+        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.
 
         Args:
           days: Last number of days to retrieve analytics for. Defaults to 365. Maximum 1825.
@@ -1363,15 +1365,14 @@ class AsyncParticipantResource(AsyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ParticipantBulkDeleteResponse:
-        """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.
+        """
+        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.
 
         Args:
           participants: GrowSurf participant IDs and/or email addresses to delete. Mixed entries are
@@ -1418,9 +1419,8 @@ class AsyncParticipantResource(AsyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> Participant:
-        """Adds a new participant to the program.
-
-        If the email already exists, the existing
+        """
+        Adds a new participant to the program. If the email already exists, the existing
         participant is returned.
 
         Args:
@@ -1485,7 +1485,8 @@ class AsyncParticipantResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ParticipantCommissionList:
         """
-        Retrieves a paged list of commissions earned by a participant.
+        **Affiliate programs only.** Retrieves a paged list of commissions earned by a
+        participant.
 
         Args:
           limit: Number of results to return. Maximum 100.
@@ -1547,7 +1548,8 @@ class AsyncParticipantResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ParticipantPayoutList:
         """
-        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.
 
         Args:
           limit: Number of results to return. Maximum 100.
@@ -1774,16 +1776,12 @@ class AsyncParticipantResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ParticipantRecordTransactionResponse:
         """
-        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.
 
         Args:
           extra_headers: Send extra headers
@@ -1873,11 +1871,12 @@ class AsyncParticipantResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ParticipantRefundTransactionResponse:
         """
-        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.
-        Commissions already paid out are not clawed back; the amendment is recorded for
-        tax reporting only.
+        **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.
 
         Args:
           extra_headers: Send extra headers
@@ -1943,8 +1942,7 @@ class AsyncParticipantResource(AsyncAPIResource):
     ) -> ParticipantSendInvitesResponse:
         """
         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.
 
         Args:
@@ -1997,7 +1995,10 @@ class AsyncParticipantResource(AsyncAPIResource):
     ) -> ParticipantTriggerReferralResponse:
         """
         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).
 
         Args:
           delay_in_days: Number of whole days to hold referral credit before it is awarded. Useful for
@@ -2048,8 +2049,11 @@ class AsyncParticipantResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ParticipantTriggerReferralResponse:
         """
-        Cancels a pending delayed referral trigger for a 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`.
 
         Args:
           extra_headers: Send extra headers
@@ -2095,14 +2099,14 @@ class AsyncParticipantResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> EmailParticipantResponse:
         """
-        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.
 
         Args:
           email_type: The program email template to trigger (template mode). The valid values depend on
@@ -2234,9 +2238,9 @@ class AsyncParticipantResource(AsyncAPIResource):
     ) -> ParticipantAnalyticsResponse:
         """
         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. Pass
-        ``include=series`` to also get this participant's own activity over time.
+        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.
 
         Args:
           days: Last number of days to retrieve analytics for. Defaults to 365. Maximum 1825.

growsurf/resources/campaign/reward.py

@@ -96,8 +96,9 @@ class RewardResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> RewardApproveResponse:
         """
-        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`.
 
         Args:
           fulfill: Set true to mark the reward as fulfilled after approval.
@@ -136,7 +137,7 @@ class RewardResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> RewardFulfillResponse:
         """
-        Marks an approved participant reward as fulfilled. Requires `reward:fulfill`.
+        Marks an approved participant reward as fulfilled.
 
         Args:
           extra_headers: Send extra headers
@@ -233,8 +234,9 @@ class AsyncRewardResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> RewardApproveResponse:
         """
-        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`.
 
         Args:
           fulfill: Set true to mark the reward as fulfilled after approval.
@@ -273,7 +275,7 @@ class AsyncRewardResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> RewardFulfillResponse:
         """
-        Marks an approved participant reward as fulfilled. Requires `reward:fulfill`.
+        Marks an approved participant reward as fulfilled.
 
         Args:
           extra_headers: Send extra headers

growsurf/resources/campaign/rewards.py

@@ -83,10 +83,11 @@ class RewardsResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> Reward:
         """
-        Creates a new campaign reward (`CampaignReward`) with a server-generated 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.
+        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.
 
         Args:
           type: The reward type. Immutable after creation.
@@ -209,7 +210,10 @@ class RewardsResource(SyncAPIResource):
     ) -> Reward:
         """
         Updates an existing campaign reward (`CampaignReward`). The reward `type` is
-        immutable and cannot be changed.
+        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.
 
         Args:
           commission_structure: The affiliate commission structure (AFFILIATE rewards only).
@@ -309,8 +313,9 @@ class RewardsResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> CampaignRewardListResponse:
         """
-        Retrieves the list of a program's configured rewards (`CampaignReward`s), the same
-        set embedded in the `rewards` array of the campaign response.
+        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}`.
 
         Args:
           extra_headers: Send extra headers
@@ -346,7 +351,9 @@ class RewardsResource(SyncAPIResource):
         """
         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.
+        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.
 
         Args:
           extra_headers: Send extra headers
@@ -425,10 +432,11 @@ class AsyncRewardsResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> Reward:
         """
-        Creates a new campaign reward (`CampaignReward`) with a server-generated 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.
+        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.
 
         Args:
           type: The reward type. Immutable after creation.
@@ -551,7 +559,10 @@ class AsyncRewardsResource(AsyncAPIResource):
     ) -> Reward:
         """
         Updates an existing campaign reward (`CampaignReward`). The reward `type` is
-        immutable and cannot be changed.
+        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.
 
         Args:
           commission_structure: The affiliate commission structure (AFFILIATE rewards only).
@@ -651,8 +662,9 @@ class AsyncRewardsResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> CampaignRewardListResponse:
         """
-        Retrieves the list of a program's configured rewards (`CampaignReward`s), the same
-        set embedded in the `rewards` array of the campaign response.
+        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}`.
 
         Args:
           extra_headers: Send extra headers
@@ -688,7 +700,9 @@ class AsyncRewardsResource(AsyncAPIResource):
         """
         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.
+        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.
 
         Args:
           extra_headers: Send extra headers

growsurf/resources/team.py

@@ -44,10 +44,10 @@ class TeamResource(SyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> Team:
-        """Retrieve 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.
         """
         return self._get(
             "/team",
@@ -66,9 +66,10 @@ class TeamResource(SyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> Team:
-        """Update the bound team's display name.
-
-        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.
 
         Args:
           name: The team's display name.
@@ -98,11 +99,16 @@ class TeamResource(SyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> RotateApiKeyResponse:
-        """Rotate the API key used for this request.
-
-        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.
         """
         return self._post(
             "/api-key/rotate",
@@ -120,9 +126,10 @@ class TeamResource(SyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> Team:
-        """Request 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`.
         """
         return self._post(
             "/team/verification-request",
@@ -140,9 +147,12 @@ class TeamResource(SyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> VerificationEmailResponse:
-        """Resend the email-verification message to the bound team's owner.
-
-        The response never reveals the owner's email address.
+        """
+        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.
         """
         return self._post(
             "/team/owner/verification-email",
@@ -174,10 +184,10 @@ class AsyncTeamResource(AsyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> Team:
-        """Retrieve 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.
         """
         return await self._get(
             "/team",
@@ -196,9 +206,10 @@ class AsyncTeamResource(AsyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> Team:
-        """Update the bound team's display name.
-
-        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.
 
         Args:
           name: The team's display name.
@@ -228,11 +239,16 @@ class AsyncTeamResource(AsyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> RotateApiKeyResponse:
-        """Rotate the API key used for this request.
-
-        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.
         """
         return await self._post(
             "/api-key/rotate",
@@ -250,9 +266,10 @@ class AsyncTeamResource(AsyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> Team:
-        """Request 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`.
         """
         return await self._post(
             "/team/verification-request",
@@ -270,9 +287,12 @@ class AsyncTeamResource(AsyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> VerificationEmailResponse:
-        """Resend the email-verification message to the bound team's owner.
-
-        The response never reveals the owner's email address.
+        """
+        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.
         """
         return await self._post(
             "/team/owner/verification-email",

{growsurf_python-1.2.0.dist-info → growsurf_python-1.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: growsurf-python
-Version: 1.2.0
+Version: 1.2.1
 Summary: The official Python library for the growsurf API
 Project-URL: Homepage, https://github.com/growsurf/growsurf-python
 Project-URL: Repository, https://github.com/growsurf/growsurf-python

{growsurf_python-1.2.0.dist-info → growsurf_python-1.2.1.dist-info}/RECORD

@@ -11,7 +11,7 @@ growsurf/_resource.py,sha256=oeDA0FL2ottIchoUi86M_8eUqmtrGQLYTgfKYEzrsWg,1112
 growsurf/_response.py,sha256=RTZ8t27W4S6ExkCjzCg4HbcDUTCdOMgiheiMAuAxgu4,28937
 growsurf/_streaming.py,sha256=9aJ_V6JtddntWCon2Cq_MOLMnySnhc7wuqeZx7sUtKU,10558
 growsurf/_types.py,sha256=r8hAVihrutiLUToaJhSDys9T9sMc8BMy2qUrr3W_8Wo,7751
-growsurf/_version.py,sha256=OWpo4konL_MQCWCiNFp1FuwA_WcSPNEK3iIIKN7x7aM,160
+growsurf/_version.py,sha256=a9IQzOgniCgsCGEzk7p2anAXmPo3nRDKRfaIjowMDbQ,160
 growsurf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 growsurf/_utils/__init__.py,sha256=nQq-iFa5YxTaWySaLigatew5rHgTR0M75FNYm4mrO1s,2313
 growsurf/_utils/_compat.py,sha256=33246eDcl3pwL6kWsEhVuT4Akrd8gZEW9LPTm465ohk,1231
@@ -29,18 +29,18 @@ growsurf/_utils/_typing.py,sha256=N_5PPuFNsaygbtA_npZd98SVN1LQQvFTKL6bkWPBZGU,47
 growsurf/_utils/_utils.py,sha256=2nPOzDrPe2GADpLCRM4bNQS8Mu7LjEiCG_LJ2AAL6jg,13111
 growsurf/lib/.keep,sha256=wuNrz-5SXo3jJaJOJgz4vFHM41YH_g20F5cRQo0vLes,224
 growsurf/resources/__init__.py,sha256=RYj6vjnPpErdBftiCuJtbwqGAnll4jXw6sg4qh6o988,1465
-growsurf/resources/account.py,sha256=dcSGZl3B0zgvDwdb8_RC0rBJXhs6pMwEDePWEiOZuNc,6727
-growsurf/resources/team.py,sha256=D6Qs011ggaeqOHW8aZRAPvgGVG4JRqVPq626ptvWGg4,12339
+growsurf/resources/account.py,sha256=1dxuYvHbt2YntkUxOYCWJQvUslsKnUDGnx7akltOQOs,8347
+growsurf/resources/team.py,sha256=-MEVGrI3hEAl-j_aMnS07CPd0SJI_KwP6XqEqrLS9KQ,14367
 growsurf/resources/campaign/__init__.py,sha256=XW5nmnR2dF-wzM0d9aoF5cZDC7c-XyyIOjdmPV8IPZ8,4875
-growsurf/resources/campaign/campaign.py,sha256=pUW-O7y3B5pfuQyv9xsDRWkRKXnuQuFvEIsjAweqURI,75421
-growsurf/resources/campaign/commission.py,sha256=K5HmznRM7nO-VNiP2Jy1rIeW63rAx1Aa2M9DEJ9dB2I,10294
-growsurf/resources/campaign/design.py,sha256=H2Syg6ASogYxrPRB9YG4VhQtGp89FRJm-AQOu5g572U,10762
-growsurf/resources/campaign/emails.py,sha256=wGGP1hTPKGb-O7wRAvkGsMflKaoPMhpXyq2ZPfJ-Xng,11060
-growsurf/resources/campaign/installation.py,sha256=36WbjO6ZDh_dDR4VHLNRxrgjbtkwYb6CbaPSc3KdbSw,11234
-growsurf/resources/campaign/options.py,sha256=OfXOBysKf7VW3IJFv7bSOcPnMXSETolRGiV2n6Ff0pQ,11130
-growsurf/resources/campaign/participant.py,sha256=4a8fU_nNTMa1txWG9eNXKybNPrT3N-lwl20BwHpHAoo,106586
-growsurf/resources/campaign/reward.py,sha256=CLRzQywVF6zpjVG2S4OIKyBhaS9B9Obrjk6ENOicb30,14264
-growsurf/resources/campaign/rewards.py,sha256=x-fZvvo0gx--SEw_r1t6HHEr6aU5Ir4kh2pqFTsxiqw,34425
+growsurf/resources/campaign/campaign.py,sha256=jk70Zl6uCyL5mukzns9Gk4FTDJE8ecrDto60hPmdBGk,75353
+growsurf/resources/campaign/commission.py,sha256=Li8L2l8xRh4EXa_oD7R9RJ6m4xaA4pmt9gXTxib2Fkk,10426
+growsurf/resources/campaign/design.py,sha256=pzc2GNaQNV1ZBvFhZwE_dosj-AWcKHJ46nCs_3i73rY,10926
+growsurf/resources/campaign/emails.py,sha256=kECJC5jUUAw5RmarBfOAktGkXmg-5DFKTwcHN4ygVMc,10816
+growsurf/resources/campaign/installation.py,sha256=mci_W2MGTHm23JgEVfIpmw_qbBNkSHgW636f6O89iPs,11198
+growsurf/resources/campaign/options.py,sha256=VFwGYniEsHg8sAd4CIt48jJU9nmdi9P_kkaw4J3iz7o,10866
+growsurf/resources/campaign/participant.py,sha256=6cC-iQ2S3jVhdVAUdif5zHI_1VQ7c3roZGTIIECfQM8,107764
+growsurf/resources/campaign/reward.py,sha256=-TiRwBcG5UwdNO_ath3pL36Bimji2QXCxSFNW8Scanw,14308
+growsurf/resources/campaign/rewards.py,sha256=ET2_vPRJp96P1kzawtTxaXtSF8hLzf98flqSELcHRj4,35555
 growsurf/resources/campaign/webhooks.py,sha256=DRJ8-8QDibGEq1hT7MTkrlE5kdbEapZXiZb2z_kKM68,22666
 growsurf/types/__init__.py,sha256=Au2V8z6APUZOYt-Lyy5X34gODWokEk_4jTWVnCmcZTg,2317
 growsurf/types/account_create_params.py,sha256=BXaWsGsiiSbYvVy6ftPNwu7nA2m1xI4PvE1xGEoGeCo,602
@@ -121,7 +121,7 @@ growsurf/types/campaign/webhook_list_response.py,sha256=tSk9nTbcsj5Y-j4RjQwu9SZc
 growsurf/types/campaign/webhook_test_params.py,sha256=X1Osg9-4KGJbZauG_7rDqTE7cKCypeSzgumIhnxj9dk,468
 growsurf/types/campaign/webhook_test_response.py,sha256=AahcckKSLUeIgpwlosOOmbkioF62xREXgLbieHAPAdI,576
 growsurf/types/campaign/webhook_update_params.py,sha256=SavKhws8pfybC7O40ovtCreEmOwihEGPOCEX9Iua9cE,598
-growsurf_python-1.2.0.dist-info/METADATA,sha256=qGVu3HTUNcU26QnNkT9VzK0nnQllwmV63d6NSG1or5U,13614
-growsurf_python-1.2.0.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-growsurf_python-1.2.0.dist-info/licenses/LICENSE,sha256=kTHLVE-ra1gtTxcn395uFqcOzcErebE-mDdPNW7b8OU,11338
-growsurf_python-1.2.0.dist-info/RECORD,,
+growsurf_python-1.2.1.dist-info/METADATA,sha256=sHfDvFX8NdWuGULA2BtJh3vzAMqIez9-B1ybWcVziDc,13614
+growsurf_python-1.2.1.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+growsurf_python-1.2.1.dist-info/licenses/LICENSE,sha256=kTHLVE-ra1gtTxcn395uFqcOzcErebE-mDdPNW7b8OU,11338
+growsurf_python-1.2.1.dist-info/RECORD,,