activitysmith 1.4.2__tar.gz → 1.6.0__tar.gz

{activitysmith-1.4.2 → activitysmith-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: activitysmith
-Version: 1.4.2
+Version: 1.6.0
 Summary: Official ActivitySmith Python SDK
 Author-email: ActivitySmith <adam@activitysmith.com>
 License: MIT
@@ -40,6 +40,8 @@ See the [API reference](https://activitysmith.com/docs/api-reference/introductio
   - [Start & Update Live Activity](#start--update-live-activity)
   - [End Live Activity](#end-live-activity)
   - [Live Activity Action](#live-activity-action)
+  - [Icons and Badges](#icons-and-badges)
+  - [Live Activity Colors](#live-activity-colors)
 - [Channels](#channels)
 - [Widgets](#widgets)
 
@@ -61,7 +63,14 @@ python -m pip install .
 
 ```python
 import os
-from activitysmith import ActivitySmith, action, content_state, metric
+from activitysmith import (
+    ActivitySmith,
+    action,
+    alert_badge,
+    alert_icon,
+    content_state,
+    metric,
+)
 
 activitysmith = ActivitySmith(
     api_key=os.environ["ACTIVITYSMITH_API_KEY"],
@@ -147,12 +156,13 @@ activitysmith.notifications.send(
 
 ## Live Activities
 
-There are four types of Live Activities:
+There are five types of Live Activities:
 
 - `stats`: best for showing business numbers side by side, such as revenue, sales, new users, conversion, refunds, or any other value you want visible at a glance
 - `metrics`: best for live percentage values that change often, like server CPU, memory usage, disk usage, or error rate
 - `segmented_progress`: best for anything that moves through clear stages, like deployments, onboarding flows, backups, ETL pipelines, migrations, and AI agent runs
 - `progress`: best for tracking real-time progress with percentage, like tasks, backups, migrations, syncs, or uploads
+- `alert`: best for status updates, such as feature adoption, reactivation, onboarding blockers, incidents, escalations, and other operational states
 
 ### Start & Update Live Activity
 
@@ -257,6 +267,29 @@ activitysmith.live_activities.stream(
 )
 ```
 
+#### Alert
+
+<p align="center">
+  <img
+    src="https://cdn.activitysmith.com/features/alert-live-activity.png"
+    alt="Alert Live Activity stream example"
+    width="680"
+  />
+</p>
+
+```python
+activitysmith.live_activities.stream(
+    "customer-ops",
+    content_state=content_state(
+        title="Reactivation",
+        message="Lumen came back after 2 weeks",
+        type="alert",
+        icon=alert_icon("cloud.sun", color="yellow"),
+        badge=alert_badge("Customer", color="magenta"),
+    ),
+)
+```
+
 ### End Live Activity
 
 Call `end_stream(...)` with the same `stream_key` to dismiss the Live Activity. You can include final values before it is removed. By default, iOS removes the Live Activity after two minutes. Set `auto_dismiss_minutes` to choose a different dismissal time, including `0` for immediate dismissal.
@@ -280,6 +313,7 @@ activitysmith.live_activities.end_stream(
 ### Live Activity Action
 
 Live Activities can include one optional action button. Use it to open a URL from the Live Activity or trigger a backend webhook.
+For Alert Live Activities, set `content_state.color` to tint the action button. `icon.color` and `badge.color` only affect the icon and badge.
 
 <p align="center">
   <img
@@ -336,6 +370,67 @@ activitysmith.live_activities.stream(
 )
 ```
 
+### Icons and Badges
+
+Add more context to Live Activities with icons and badges.
+
+#### Icon
+
+Supported Live Activity types: `stats`, `metrics`, `progress`, `segmented_progress`, and `alert`.
+
+<p align="center">
+  <img src="https://cdn.activitysmith.com/features/metrics-live-activity-with-icon.png" alt="Metrics Live Activity with an SF Symbol icon on the iPhone Lock Screen" width="680" />
+</p>
+
+```python
+activitysmith.live_activities.stream(
+    "prod-web-1",
+    content_state=content_state(
+        title="Server Health",
+        subtitle="prod-web-1",
+        type=activitysmith.live_activities.TYPE_METRICS,
+        icon=alert_icon("server.rack", color="blue"),
+        metrics=[
+            metric(label="CPU", value=18, unit="%"),
+            metric(label="MEM", value=42, unit="%"),
+        ],
+    ),
+)
+```
+
+The `icon.symbol` value is an Apple SF Symbol name. Browse the catalog with one of these tools:
+
+- [ActivitySmith app](https://apps.apple.com/us/app/activitysmith/id6752254835) - Open Settings -> SF Symbols to browse 45 hand-picked icons ready to use
+- [SF Symbols](https://developer.apple.com/sf-symbols/) - Apple's official macOS app
+- [Interactful](https://apps.apple.com/app/interactful/id1528095640) - free third-party iOS app listing all SF Symbols under Foundations -> Iconography
+
+#### Badge
+
+Badges are supported by `alert`, `progress`, and `segmented_progress` Live Activities.
+
+<p align="center">
+  <img src="https://cdn.activitysmith.com/features/progress-live-activity-with-badge.png" alt="Progress Live Activity with a badge on the iPhone Lock Screen" width="680" />
+</p>
+
+```python
+activitysmith.live_activities.stream(
+    "nightly-database-backup",
+    content_state=content_state(
+        title="Nightly Database Backup",
+        subtitle="verify restore",
+        type=activitysmith.live_activities.TYPE_PROGRESS,
+        badge=alert_badge("S3", color="cyan"),
+        percentage=62,
+    ),
+)
+```
+
+### Live Activity Colors
+
+Choose from these colors for the Live Activity accent, including progress bars and action buttons, or apply them to an individual icon or badge:
+
+`lime`, `green`, `cyan`, `blue`, `purple`, `magenta`, `red`, `orange`, `yellow`, `gray`
+
 ## Channels
 
 Channels are used to target specific team members or devices. Can be used for both push notifications and live activities.

{activitysmith-1.4.2 → activitysmith-1.6.0}/README.md

@@ -18,6 +18,8 @@ See the [API reference](https://activitysmith.com/docs/api-reference/introductio
   - [Start & Update Live Activity](#start--update-live-activity)
   - [End Live Activity](#end-live-activity)
   - [Live Activity Action](#live-activity-action)
+  - [Icons and Badges](#icons-and-badges)
+  - [Live Activity Colors](#live-activity-colors)
 - [Channels](#channels)
 - [Widgets](#widgets)
 
@@ -39,7 +41,14 @@ python -m pip install .
 
 ```python
 import os
-from activitysmith import ActivitySmith, action, content_state, metric
+from activitysmith import (
+    ActivitySmith,
+    action,
+    alert_badge,
+    alert_icon,
+    content_state,
+    metric,
+)
 
 activitysmith = ActivitySmith(
     api_key=os.environ["ACTIVITYSMITH_API_KEY"],
@@ -125,12 +134,13 @@ activitysmith.notifications.send(
 
 ## Live Activities
 
-There are four types of Live Activities:
+There are five types of Live Activities:
 
 - `stats`: best for showing business numbers side by side, such as revenue, sales, new users, conversion, refunds, or any other value you want visible at a glance
 - `metrics`: best for live percentage values that change often, like server CPU, memory usage, disk usage, or error rate
 - `segmented_progress`: best for anything that moves through clear stages, like deployments, onboarding flows, backups, ETL pipelines, migrations, and AI agent runs
 - `progress`: best for tracking real-time progress with percentage, like tasks, backups, migrations, syncs, or uploads
+- `alert`: best for status updates, such as feature adoption, reactivation, onboarding blockers, incidents, escalations, and other operational states
 
 ### Start & Update Live Activity
 
@@ -235,6 +245,29 @@ activitysmith.live_activities.stream(
 )
 ```
 
+#### Alert
+
+<p align="center">
+  <img
+    src="https://cdn.activitysmith.com/features/alert-live-activity.png"
+    alt="Alert Live Activity stream example"
+    width="680"
+  />
+</p>
+
+```python
+activitysmith.live_activities.stream(
+    "customer-ops",
+    content_state=content_state(
+        title="Reactivation",
+        message="Lumen came back after 2 weeks",
+        type="alert",
+        icon=alert_icon("cloud.sun", color="yellow"),
+        badge=alert_badge("Customer", color="magenta"),
+    ),
+)
+```
+
 ### End Live Activity
 
 Call `end_stream(...)` with the same `stream_key` to dismiss the Live Activity. You can include final values before it is removed. By default, iOS removes the Live Activity after two minutes. Set `auto_dismiss_minutes` to choose a different dismissal time, including `0` for immediate dismissal.
@@ -258,6 +291,7 @@ activitysmith.live_activities.end_stream(
 ### Live Activity Action
 
 Live Activities can include one optional action button. Use it to open a URL from the Live Activity or trigger a backend webhook.
+For Alert Live Activities, set `content_state.color` to tint the action button. `icon.color` and `badge.color` only affect the icon and badge.
 
 <p align="center">
   <img
@@ -314,6 +348,67 @@ activitysmith.live_activities.stream(
 )
 ```
 
+### Icons and Badges
+
+Add more context to Live Activities with icons and badges.
+
+#### Icon
+
+Supported Live Activity types: `stats`, `metrics`, `progress`, `segmented_progress`, and `alert`.
+
+<p align="center">
+  <img src="https://cdn.activitysmith.com/features/metrics-live-activity-with-icon.png" alt="Metrics Live Activity with an SF Symbol icon on the iPhone Lock Screen" width="680" />
+</p>
+
+```python
+activitysmith.live_activities.stream(
+    "prod-web-1",
+    content_state=content_state(
+        title="Server Health",
+        subtitle="prod-web-1",
+        type=activitysmith.live_activities.TYPE_METRICS,
+        icon=alert_icon("server.rack", color="blue"),
+        metrics=[
+            metric(label="CPU", value=18, unit="%"),
+            metric(label="MEM", value=42, unit="%"),
+        ],
+    ),
+)
+```
+
+The `icon.symbol` value is an Apple SF Symbol name. Browse the catalog with one of these tools:
+
+- [ActivitySmith app](https://apps.apple.com/us/app/activitysmith/id6752254835) - Open Settings -> SF Symbols to browse 45 hand-picked icons ready to use
+- [SF Symbols](https://developer.apple.com/sf-symbols/) - Apple's official macOS app
+- [Interactful](https://apps.apple.com/app/interactful/id1528095640) - free third-party iOS app listing all SF Symbols under Foundations -> Iconography
+
+#### Badge
+
+Badges are supported by `alert`, `progress`, and `segmented_progress` Live Activities.
+
+<p align="center">
+  <img src="https://cdn.activitysmith.com/features/progress-live-activity-with-badge.png" alt="Progress Live Activity with a badge on the iPhone Lock Screen" width="680" />
+</p>
+
+```python
+activitysmith.live_activities.stream(
+    "nightly-database-backup",
+    content_state=content_state(
+        title="Nightly Database Backup",
+        subtitle="verify restore",
+        type=activitysmith.live_activities.TYPE_PROGRESS,
+        badge=alert_badge("S3", color="cyan"),
+        percentage=62,
+    ),
+)
+```
+
+### Live Activity Colors
+
+Choose from these colors for the Live Activity accent, including progress bars and action buttons, or apply them to an individual icon or badge:
+
+`lime`, `green`, `cyan`, `blue`, `purple`, `magenta`, `red`, `orange`, `yellow`, `gray`
+
 ## Channels
 
 Channels are used to target specific team members or devices. Can be used for both push notifications and live activities.

activitysmith-1.6.0/activitysmith/__init__.py

@@ -0,0 +1,19 @@
+from .client import (
+    ActivitySmith,
+    LiveActivityColor,
+    action,
+    alert_badge,
+    alert_icon,
+    content_state,
+    metric,
+)
+
+__all__ = [
+    "ActivitySmith",
+    "LiveActivityColor",
+    "action",
+    "alert_badge",
+    "alert_icon",
+    "content_state",
+    "metric",
+]

{activitysmith-1.4.2 → activitysmith-1.6.0}/activitysmith/client.py

@@ -10,7 +10,7 @@ from activitysmith_openapi.api.live_activities_api import LiveActivitiesApi
 from activitysmith_openapi.api.metrics_api import MetricsApi
 from activitysmith_openapi.api.push_notifications_api import PushNotificationsApi
 
-SDK_VERSION = "1.4.1"
+SDK_VERSION = "1.6.0"
 SDK_HEADER_NAME = "X-ActivitySmith-SDK"
 SDK_HEADER_VALUE = f"python-v{SDK_VERSION}"
 
@@ -122,11 +122,44 @@ def action(
     )
 
 
+def alert_icon(
+    symbol: str,
+    *,
+    color: str | None = None,
+) -> dict[str, Any]:
+    return _compact_dict(
+        {
+            "symbol": symbol,
+            "color": color,
+        }
+    )
+
+
+def alert_badge(
+    title: str,
+    *,
+    color: str | None = None,
+) -> dict[str, Any]:
+    return _compact_dict(
+        {
+            "title": title,
+            "color": color,
+        }
+    )
+
+
+def _normalize_live_activity_content_state(content_state: Any) -> Any:
+    return content_state
+
+
 def content_state(
     title: str,
     *,
     type: str | None = None,
     subtitle: str | None = None,
+    message: str | None = None,
+    icon: Any | None = None,
+    badge: Any | None = None,
     metrics: Any | None = None,
     number_of_steps: int | None = None,
     current_step: int | None = None,
@@ -138,11 +171,14 @@ def content_state(
     auto_dismiss_seconds: int | None = None,
     auto_dismiss_minutes: int | None = None,
 ) -> dict[str, Any]:
-    return _compact_dict(
+    state = _compact_dict(
         {
             "title": title,
             "subtitle": subtitle,
             "type": type,
+            "message": message,
+            "icon": icon,
+            "badge": badge,
             "metrics": metrics,
             "number_of_steps": number_of_steps,
             "current_step": current_step,
@@ -155,6 +191,7 @@ def content_state(
             "auto_dismiss_minutes": auto_dismiss_minutes,
         }
     )
+    return _normalize_live_activity_content_state(state)
 
 
 def _build_push_request(
@@ -208,6 +245,7 @@ class LiveActivityColor:
     RED = "red"
     ORANGE = "orange"
     YELLOW = "yellow"
+    GRAY = "gray"
 
 
 def _build_live_activity_request(
@@ -218,6 +256,9 @@ def _build_live_activity_request(
     title: Any | None = None,
     subtitle: Any | None = None,
     type: Any | None = None,
+    message: Any | None = None,
+    icon: Any | None = None,
+    badge: Any | None = None,
     metrics: Any | None = None,
     number_of_steps: Any | None = None,
     current_step: Any | None = None,
@@ -238,6 +279,9 @@ def _build_live_activity_request(
             "title": title,
             "subtitle": subtitle,
             "type": type,
+            "message": message,
+            "icon": icon,
+            "badge": badge,
             "metrics": metrics,
             "number_of_steps": number_of_steps,
             "current_step": current_step,
@@ -250,6 +294,7 @@ def _build_live_activity_request(
             "auto_dismiss_minutes": auto_dismiss_minutes,
         }
     )
+    content_state_fields = _normalize_live_activity_content_state(content_state_fields)
     request_fields = _compact_dict(
         {
             "activity_id": activity_id,
@@ -273,6 +318,7 @@ def _build_live_activity_request(
         )
 
     if content_state is not None:
+        content_state = _normalize_live_activity_content_state(content_state)
         existing_content_state = normalized.get("content_state")
         if existing_content_state is None:
             normalized["content_state"] = content_state
@@ -289,6 +335,9 @@ def _build_live_activity_request(
             normalized["content_state"] = {**existing_content_state, **content_state_fields}
         else:
             raise TypeError("ActivitySmith: content_state must be a dict")
+        normalized["content_state"] = _normalize_live_activity_content_state(
+            normalized["content_state"]
+        )
 
     normalized.update(request_fields)
     return normalized
@@ -337,6 +386,7 @@ class LiveActivitiesResource:
     TYPE_PROGRESS = "progress"
     TYPE_METRICS = "metrics"
     TYPE_STATS = "stats"
+    TYPE_ALERT = "alert"
 
     def __init__(self, api: LiveActivitiesApi) -> None:
         self._api = api
@@ -351,6 +401,22 @@ class LiveActivitiesResource:
     ) -> dict[str, Any]:
         return metric(label, value, unit=unit, color=color)
 
+    @staticmethod
+    def alert_icon(
+        symbol: str,
+        *,
+        color: str | None = None,
+    ) -> dict[str, Any]:
+        return alert_icon(symbol, color=color)
+
+    @staticmethod
+    def alert_badge(
+        title: str,
+        *,
+        color: str | None = None,
+    ) -> dict[str, Any]:
+        return alert_badge(title, color=color)
+
     def start(
         self,
         request: Any | None = None,
@@ -359,6 +425,9 @@ class LiveActivitiesResource:
         title: Any | None = None,
         subtitle: Any | None = None,
         type: Any | None = None,
+        message: Any | None = None,
+        icon: Any | None = None,
+        badge: Any | None = None,
         metrics: Any | None = None,
         number_of_steps: Any | None = None,
         current_step: Any | None = None,
@@ -378,6 +447,9 @@ class LiveActivitiesResource:
             title=title,
             subtitle=subtitle,
             type=type,
+            message=message,
+            icon=icon,
+            badge=badge,
             metrics=metrics,
             number_of_steps=number_of_steps,
             current_step=current_step,
@@ -404,6 +476,9 @@ class LiveActivitiesResource:
         title: Any | None = None,
         subtitle: Any | None = None,
         type: Any | None = None,
+        message: Any | None = None,
+        icon: Any | None = None,
+        badge: Any | None = None,
         metrics: Any | None = None,
         number_of_steps: Any | None = None,
         current_step: Any | None = None,
@@ -421,6 +496,9 @@ class LiveActivitiesResource:
             title=title,
             subtitle=subtitle,
             type=type,
+            message=message,
+            icon=icon,
+            badge=badge,
             metrics=metrics,
             number_of_steps=number_of_steps,
             current_step=current_step,
@@ -442,6 +520,9 @@ class LiveActivitiesResource:
         title: Any | None = None,
         subtitle: Any | None = None,
         type: Any | None = None,
+        message: Any | None = None,
+        icon: Any | None = None,
+        badge: Any | None = None,
         metrics: Any | None = None,
         number_of_steps: Any | None = None,
         current_step: Any | None = None,
@@ -460,6 +541,9 @@ class LiveActivitiesResource:
             title=title,
             subtitle=subtitle,
             type=type,
+            message=message,
+            icon=icon,
+            badge=badge,
             metrics=metrics,
             number_of_steps=number_of_steps,
             current_step=current_step,
@@ -482,6 +566,9 @@ class LiveActivitiesResource:
         title: Any | None = None,
         subtitle: Any | None = None,
         type: Any | None = None,
+        message: Any | None = None,
+        icon: Any | None = None,
+        badge: Any | None = None,
         metrics: Any | None = None,
         number_of_steps: Any | None = None,
         current_step: Any | None = None,
@@ -501,6 +588,9 @@ class LiveActivitiesResource:
             title=title,
             subtitle=subtitle,
             type=type,
+            message=message,
+            icon=icon,
+            badge=badge,
             metrics=metrics,
             number_of_steps=number_of_steps,
             current_step=current_step,
@@ -528,6 +618,9 @@ class LiveActivitiesResource:
         title: Any | None = None,
         subtitle: Any | None = None,
         type: Any | None = None,
+        message: Any | None = None,
+        icon: Any | None = None,
+        badge: Any | None = None,
         metrics: Any | None = None,
         number_of_steps: Any | None = None,
         current_step: Any | None = None,
@@ -546,6 +639,9 @@ class LiveActivitiesResource:
             title=title,
             subtitle=subtitle,
             type=type,
+            message=message,
+            icon=icon,
+            badge=badge,
             metrics=metrics,
             number_of_steps=number_of_steps,
             current_step=current_step,