growsurf-python 1.3.0__tar.gz → 1.4.0__tar.gz

growsurf_python-1.4.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "1.4.0"
+}

{growsurf_python-1.3.0 → growsurf_python-1.4.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.4.0](https://github.com/growsurf/growsurf-python/compare/v1.3.0...v1.4.0) (2026-08-25)
+
+
+### Features
+
+* **api:** add reward and commission event support ([a8b2506](https://github.com/growsurf/growsurf-python/commit/a8b25066fc91b7a144b4a718911f8f2123bdecb3))
+
 ## [1.3.0](https://github.com/growsurf/growsurf-python/compare/v1.2.1...v1.3.0) (2026-08-23)
 
 

{growsurf_python-1.3.0 → growsurf_python-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: growsurf-python
-Version: 1.3.0
+Version: 1.4.0
 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.3.0 → growsurf_python-1.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "growsurf-python"
-version = "1.3.0"
+version = "1.4.0"
 description = "The official Python library for the growsurf API"
 dynamic = ["readme"]
 license = "Apache-2.0"

{growsurf_python-1.3.0 → growsurf_python-1.4.0}/src/growsurf/_version.py

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

{growsurf_python-1.3.0 → growsurf_python-1.4.0}/src/growsurf/resources/campaign/participant.py

@@ -1146,13 +1146,17 @@ class ParticipantResource(SyncAPIResource):
         for `sent` (accepted for delivery), `delivered`, `opened`, `clicked`,
         `bounced`, and `spamComplaints` metrics attributed to this participant,
         including invitations they sent. Use `include=email,series` to include the
-        same counts in each UTC series bucket.
+        same counts in each UTC series bucket. `days`, `startDate`, and `endDate`
+        filter only the optional `series` and `email` data. They do not filter the
+        top-level `analytics`, `ranks`, or `shareCount` values.
 
         Args:
-          days: Last number of days to retrieve analytics for. Defaults to 365. Maximum 1825.
+          days: Last number of days for optional `series` and `email` analytics.
+              Defaults to 365. Maximum 1825. Does not filter the top-level all-time totals.
 
-          end_date: End date of the analytics timeframe as a Unix timestamp in milliseconds.
-              Required if `days` is not set.
+          end_date: End of a custom `series` and `email` analytics window as a Unix
+              timestamp in milliseconds. Set it together with `startDate`. Does not filter
+              the top-level all-time totals.
 
           include: Comma-separated optional data. `series` returns this participant's own
               activity per period; `email` returns `sent`, `delivered`, `opened`, `clicked`,
@@ -1165,8 +1169,9 @@ class ParticipantResource(SyncAPIResource):
           interval: Bucket size for the `series` (only used when `include` contains `series`).
               Defaults to `day`.
 
-          start_date: Start date of the analytics timeframe as a Unix timestamp in milliseconds.
-              Required if `days` is not set.
+          start_date: Start of a custom `series` and `email` analytics window as a Unix
+              timestamp in milliseconds. Set it together with `endDate`. Does not filter
+              the top-level all-time totals.
 
           extra_headers: Send extra headers
 
@@ -2393,13 +2398,17 @@ class AsyncParticipantResource(AsyncAPIResource):
         for `sent` (accepted for delivery), `delivered`, `opened`, `clicked`,
         `bounced`, and `spamComplaints` metrics attributed to this participant,
         including invitations they sent. Use `include=email,series` to include the
-        same counts in each UTC series bucket.
+        same counts in each UTC series bucket. `days`, `startDate`, and `endDate`
+        filter only the optional `series` and `email` data. They do not filter the
+        top-level `analytics`, `ranks`, or `shareCount` values.
 
         Args:
-          days: Last number of days to retrieve analytics for. Defaults to 365. Maximum 1825.
+          days: Last number of days for optional `series` and `email` analytics.
+              Defaults to 365. Maximum 1825. Does not filter the top-level all-time totals.
 
-          end_date: End date of the analytics timeframe as a Unix timestamp in milliseconds.
-              Required if `days` is not set.
+          end_date: End of a custom `series` and `email` analytics window as a Unix
+              timestamp in milliseconds. Set it together with `startDate`. Does not filter
+              the top-level all-time totals.
 
           include: Comma-separated optional data. `series` returns this participant's own
               activity per period; `email` returns `sent`, `delivered`, `opened`, `clicked`,
@@ -2412,8 +2421,9 @@ class AsyncParticipantResource(AsyncAPIResource):
           interval: Bucket size for the `series` (only used when `include` contains `series`).
               Defaults to `day`.
 
-          start_date: Start date of the analytics timeframe as a Unix timestamp in milliseconds.
-              Required if `days` is not set.
+          start_date: Start of a custom `series` and `email` analytics window as a Unix
+              timestamp in milliseconds. Set it together with `endDate`. Does not filter
+              the top-level all-time totals.
 
           extra_headers: Send extra headers
 

{growsurf_python-1.3.0 → growsurf_python-1.4.0}/src/growsurf/resources/campaign/rewards.py

@@ -59,6 +59,7 @@ class RewardsResource(SyncAPIResource):
         conversions_required: int | Omit = omit,
         coupon_code: Optional[str] | Omit = omit,
         description: str | Omit = omit,
+        event: Literal["LEAD", "CONVERSION"] | Omit = omit,
         image_url: Optional[str] | Omit = omit,
         is_unlimited: bool | Omit = omit,
         is_visible: bool | Omit = omit,
@@ -98,6 +99,11 @@ class RewardsResource(SyncAPIResource):
 
           description: The reward description shown to the referrer.
 
+          event: The event that earns this Campaign Reward. `SINGLE_SIDED`,
+              `DOUBLE_SIDED`, and `MILESTONE` rewards support `LEAD` or `CONVERSION`.
+              `LEAD` requires `installation.referralTrigger` to be `CUSTOM`. Omitting
+              `event` defaults to `CONVERSION`.
+
           image_url: An image URL for the reward.
 
           is_unlimited: Whether the reward can be earned an unlimited number of times. Defaults to
@@ -150,6 +156,7 @@ class RewardsResource(SyncAPIResource):
                     "conversions_required": conversions_required,
                     "coupon_code": coupon_code,
                     "description": description,
+                    "event": event,
                     "image_url": image_url,
                     "is_unlimited": is_unlimited,
                     "is_visible": is_visible,
@@ -184,6 +191,7 @@ class RewardsResource(SyncAPIResource):
         conversions_required: int | Omit = omit,
         coupon_code: Optional[str] | Omit = omit,
         description: str | Omit = omit,
+        event: Literal["LEAD", "CONVERSION"] | Omit = omit,
         image_url: Optional[str] | Omit = omit,
         is_unlimited: bool | Omit = omit,
         is_visible: bool | Omit = omit,
@@ -219,6 +227,11 @@ class RewardsResource(SyncAPIResource):
 
           conversions_required: The number of referrals required to earn the reward.
 
+          event: The event that earns this Campaign Reward. `SINGLE_SIDED`,
+              `DOUBLE_SIDED`, and `MILESTONE` rewards support `LEAD` or `CONVERSION`.
+              `LEAD` requires `installation.referralTrigger` to be `CUSTOM`. Omitting
+              `event` preserves the Campaign Reward's current event.
+
           description: The reward description shown to the referrer.
 
           image_url: An image URL for the reward.
@@ -276,6 +289,7 @@ class RewardsResource(SyncAPIResource):
                     "conversions_required": conversions_required,
                     "coupon_code": coupon_code,
                     "description": description,
+                    "event": event,
                     "image_url": image_url,
                     "is_unlimited": is_unlimited,
                     "is_visible": is_visible,
@@ -410,6 +424,7 @@ class AsyncRewardsResource(AsyncAPIResource):
         conversions_required: int | Omit = omit,
         coupon_code: Optional[str] | Omit = omit,
         description: str | Omit = omit,
+        event: Literal["LEAD", "CONVERSION"] | Omit = omit,
         image_url: Optional[str] | Omit = omit,
         is_unlimited: bool | Omit = omit,
         is_visible: bool | Omit = omit,
@@ -449,6 +464,11 @@ class AsyncRewardsResource(AsyncAPIResource):
 
           description: The reward description shown to the referrer.
 
+          event: The event that earns this Campaign Reward. `SINGLE_SIDED`,
+              `DOUBLE_SIDED`, and `MILESTONE` rewards support `LEAD` or `CONVERSION`.
+              `LEAD` requires `installation.referralTrigger` to be `CUSTOM`. Omitting
+              `event` defaults to `CONVERSION`.
+
           image_url: An image URL for the reward.
 
           is_unlimited: Whether the reward can be earned an unlimited number of times. Defaults to
@@ -501,6 +521,7 @@ class AsyncRewardsResource(AsyncAPIResource):
                     "conversions_required": conversions_required,
                     "coupon_code": coupon_code,
                     "description": description,
+                    "event": event,
                     "image_url": image_url,
                     "is_unlimited": is_unlimited,
                     "is_visible": is_visible,
@@ -535,6 +556,7 @@ class AsyncRewardsResource(AsyncAPIResource):
         conversions_required: int | Omit = omit,
         coupon_code: Optional[str] | Omit = omit,
         description: str | Omit = omit,
+        event: Literal["LEAD", "CONVERSION"] | Omit = omit,
         image_url: Optional[str] | Omit = omit,
         is_unlimited: bool | Omit = omit,
         is_visible: bool | Omit = omit,
@@ -570,6 +592,11 @@ class AsyncRewardsResource(AsyncAPIResource):
 
           conversions_required: The number of referrals required to earn the reward.
 
+          event: The event that earns this Campaign Reward. `SINGLE_SIDED`,
+              `DOUBLE_SIDED`, and `MILESTONE` rewards support `LEAD` or `CONVERSION`.
+              `LEAD` requires `installation.referralTrigger` to be `CUSTOM`. Omitting
+              `event` preserves the Campaign Reward's current event.
+
           description: The reward description shown to the referrer.
 
           image_url: An image URL for the reward.
@@ -627,6 +654,7 @@ class AsyncRewardsResource(AsyncAPIResource):
                     "conversions_required": conversions_required,
                     "coupon_code": coupon_code,
                     "description": description,
+                    "event": event,
                     "image_url": image_url,
                     "is_unlimited": is_unlimited,
                     "is_visible": is_visible,

{growsurf_python-1.3.0 → growsurf_python-1.4.0}/src/growsurf/types/campaign/campaign.py

@@ -30,6 +30,13 @@ class Reward(BaseModel):
 
     description: Optional[str] = None
 
+    event: Optional[Literal["LEAD", "CONVERSION"]] = None
+    """The event that earns this Campaign Reward.
+
+    Present only for `SINGLE_SIDED`, `DOUBLE_SIDED`, and `MILESTONE` rewards. Legacy
+    Campaign Rewards return `CONVERSION`.
+    """
+
     image_url: Optional[str] = FieldInfo(alias="imageUrl", default=None)
 
     is_visible: Optional[bool] = FieldInfo(alias="isVisible", default=None)

{growsurf_python-1.3.0 → growsurf_python-1.4.0}/src/growsurf/types/campaign/participant_analytics_params.py

@@ -13,12 +13,16 @@ class ParticipantAnalyticsParams(TypedDict, total=False):
     id: Required[str]
 
     days: int
-    """Last number of days to retrieve analytics for. Defaults to 365. Maximum 1825."""
+    """Last number of days for optional `series` and `email` analytics.
+
+    Defaults to 365. Maximum 1825. Does not filter the top-level all-time totals.
+    """
 
     end_date: Annotated[int, PropertyInfo(alias="endDate")]
-    """End date of the analytics timeframe as a Unix timestamp in milliseconds.
+    """End of a custom `series` and `email` analytics window as a Unix timestamp.
 
-    Required if `days` is not set.
+    Expressed in milliseconds. Set it together with `startDate`. Does not filter the
+    top-level all-time totals.
     """
 
     include: str
@@ -39,7 +43,8 @@ class ParticipantAnalyticsParams(TypedDict, total=False):
     """
 
     start_date: Annotated[int, PropertyInfo(alias="startDate")]
-    """Start date of the analytics timeframe as a Unix timestamp in milliseconds.
+    """Start of a custom `series` and `email` analytics window as a Unix timestamp.
 
-    Required if `days` is not set.
+    Expressed in milliseconds. Set it together with `endDate`. Does not filter the
+    top-level all-time totals.
     """

{growsurf_python-1.3.0 → growsurf_python-1.4.0}/src/growsurf/types/campaign/participant_reward.py

@@ -16,7 +16,7 @@ class ParticipantReward(BaseModel):
 
     reward_id: str = FieldInfo(alias="rewardId")
 
-    status: Literal["PENDING", "FULFILLED"]
+    status: Literal["PENDING", "FULFILLED", "CANCELLED"]
 
     approved: Optional[bool] = None
 

{growsurf_python-1.3.0 → growsurf_python-1.4.0}/src/growsurf/types/campaign/reward.py

@@ -41,6 +41,13 @@ class Reward(BaseModel):
     description: Optional[str] = None
     """The reward description shown to the referrer."""
 
+    event: Optional[Literal["LEAD", "CONVERSION"]] = None
+    """The event that earns this Campaign Reward.
+
+    Present only for `SINGLE_SIDED`, `DOUBLE_SIDED`, and `MILESTONE` rewards. Legacy
+    Campaign Rewards return `CONVERSION`.
+    """
+
     image_url: Optional[str] = FieldInfo(alias="imageUrl", default=None)
     """The reward image URL."""
 

{growsurf_python-1.3.0 → growsurf_python-1.4.0}/src/growsurf/types/campaign/reward_create_params.py

@@ -32,6 +32,14 @@ class RewardCreateParams(TypedDict, total=False):
     description: str
     """The reward description shown to the referrer."""
 
+    event: Literal["LEAD", "CONVERSION"]
+    """The event that earns this Campaign Reward.
+
+    `SINGLE_SIDED`, `DOUBLE_SIDED`, and `MILESTONE` rewards support `LEAD` or
+    `CONVERSION`. `LEAD` requires `installation.referralTrigger` to be `CUSTOM`.
+    When omitted, the Campaign Reward defaults to `CONVERSION`.
+    """
+
     image_url: Annotated[Optional[str], PropertyInfo(alias="imageUrl")]
     """An image URL for the reward."""
 

{growsurf_python-1.3.0 → growsurf_python-1.4.0}/src/growsurf/types/campaign/reward_update_params.py

@@ -31,6 +31,14 @@ class RewardUpdateParams(TypedDict, total=False):
     description: str
     """The reward description shown to the referrer."""
 
+    event: Literal["LEAD", "CONVERSION"]
+    """The event that earns this Campaign Reward.
+
+    `SINGLE_SIDED`, `DOUBLE_SIDED`, and `MILESTONE` rewards support `LEAD` or
+    `CONVERSION`. `LEAD` requires `installation.referralTrigger` to be `CUSTOM`.
+    When omitted, the Campaign Reward's current event is preserved.
+    """
+
     image_url: Annotated[Optional[str], PropertyInfo(alias="imageUrl")]
     """An image URL for the reward."""
 

{growsurf_python-1.3.0 → growsurf_python-1.4.0}/src/growsurf/types/commission_structure.py

@@ -21,7 +21,8 @@ class CommissionStructure(BaseModel):
 
     duration_in_months: Optional[int] = FieldInfo(alias="durationInMonths", default=None)
 
-    event: Optional[str] = None
+    event: Optional[Literal["CLICK", "LEAD", "SALE"]] = None
+    """The event that generates a commission. Missing legacy values read as `SALE`."""
 
     has_intro: Optional[bool] = FieldInfo(alias="hasIntro", default=None)
 

{growsurf_python-1.3.0 → growsurf_python-1.4.0}/src/growsurf/types/participant_commission_list.py

@@ -19,6 +19,9 @@ class Commission(BaseModel):
 
     currency_iso: str = FieldInfo(alias="currencyISO")
 
+    event: Literal["LEAD", "SALE"]
+    """The event that generated the commission. Legacy commissions return `SALE`."""
+
     referred_id: str = FieldInfo(alias="referredId")
 
     referrer_id: str = FieldInfo(alias="referrerId")

growsurf_python-1.4.0/tests/types/test_lead_reward_events.py

@@ -0,0 +1,62 @@
+from typing_extensions import Literal
+
+from growsurf.types.campaign.reward import Reward
+from growsurf.types.campaign.campaign import Reward as CampaignReward
+from growsurf.types.commission_structure import CommissionStructure
+from growsurf.types.campaign.participant_reward import ParticipantReward
+from growsurf.types.participant_commission_list import Commission
+
+
+def test_reward_and_commission_events_parse_from_public_wire_values() -> None:
+    reward = Reward(
+        id="crew_signup",
+        isUnlimited=True,
+        metadata={},
+        type="SINGLE_SIDED",
+        event="LEAD",
+    )
+    embedded_reward = CampaignReward(
+        id="crew_signup",
+        isUnlimited=True,
+        metadata={},
+        type="SINGLE_SIDED",
+        event="LEAD",
+    )
+    commission = Commission(
+        id="comm_signup",
+        amount=500,
+        createdAt=1,
+        currencyISO="USD",
+        event="LEAD",
+        referredId="part_friend",
+        referrerId="part_advocate",
+        saleAmount=None,
+        status="PENDING",
+    )
+
+    assert reward.event == "LEAD"
+    assert embedded_reward.event == "LEAD"
+    assert commission.event == "LEAD"
+    assert commission.sale_amount is None
+
+
+def test_cancelled_participant_reward_parses_from_public_wire_value() -> None:
+    reward = ParticipantReward(
+        id="participant_reward_cancelled",
+        rewardId="reward_cancelled",
+        status="CANCELLED",
+    )
+
+    assert reward.status == "CANCELLED"
+
+
+def test_commission_structure_exposes_supported_event_contract() -> None:
+    click = CommissionStructure(event="CLICK")
+    lead = CommissionStructure(event="LEAD")
+    sale = CommissionStructure(event="SALE")
+    assert click.event is not None
+
+    event: Literal["CLICK", "LEAD", "SALE"] = click.event
+    assert event == "CLICK"
+    assert lead.event == "LEAD"
+    assert sale.event == "SALE"

growsurf_python-1.3.0/.release-please-manifest.json

@@ -1,3 +0,0 @@
-{
-  ".": "1.3.0"
-}