activitysmith 0.1.7 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6be18d3495ded4e85d34cb9dfa10b9108f9dbd5e35ace8bd6303867fb6b31172
-  data.tar.gz: 64b2d345bf824795d5b809d0ce5e9e40ee239d7f86878c20213704892f95db4e
+  metadata.gz: 9ca64934e2eee58c310acc66bcff641a6b8e8bd7223701702d1cf913a81f7ae0
+  data.tar.gz: 752924606d9ffb0d623e81a7c3ea1c159d8eeff827e15bfea86f9350c7d10537
 SHA512:
-  metadata.gz: 72f3a210715d8e9e660142c12ba0b5ae1d99bcd87fd49196c1aa8a6f4732b6aa83fd4408b11afc5816ef3e214804dfded8ba7dd23eb1ded669f805e1067df442
-  data.tar.gz: a022698cba1e043612fb3490fe3fc8805c20ef61dd8104137d74b3f8a0b36b9e378522ce76e5b4123a520a29ce2f1359f3fad6238758a701e7e672bca508ce8f
+  metadata.gz: 5dcf355adad083329d44b3b42fbd691e60996165ccb0af954027b08d2af27fe913f6bb45cb33a225581790589b1f2ff9d42a9cacff32fbf8b23159e5ed7cbfea
+  data.tar.gz: fbd8e68d0fcf453c4431780db2883ffd906e972e5e8b240e4dc68471da0f0919730b4ee61728045e958c624a3df15b81cdc7a79bd876bb7a1d029d141630cd37

data/README.md

@@ -20,7 +20,7 @@ require "activitysmith"
 activitysmith = ActivitySmith::Client.new(api_key: ENV.fetch("ACTIVITYSMITH_API_KEY"))
 ```
 
-## Usage
+## Push Notifications
 
 ### Send a Push Notification
 
@@ -29,40 +29,306 @@ activitysmith = ActivitySmith::Client.new(api_key: ENV.fetch("ACTIVITYSMITH_API_
 </p>
 
 ```ruby
-response = activitysmith.notifications.send(
+activitysmith.notifications.send(
   {
     title: "New subscription 💸",
     message: "Customer upgraded to Pro plan"
   }
 )
+```
+
+### Rich Push Notifications with Media
+
+<p align="center">
+  <img src="https://cdn.activitysmith.com/features/rich-push-notification-with-image.png" alt="Rich push notification with image" width="680" />
+</p>
 
-puts response.success
-puts response.devices_notified
+```ruby
+activitysmith.notifications.send(
+  {
+    title: "Homepage ready",
+    message: "Your agent finished the redesign.",
+    media: "https://cdn.example.com/output/homepage-v2.png",
+    redirection: "https://github.com/acme/web/pull/482"
+  }
+)
+```
+
+Send images, videos, or audio with your push notifications, press and hold to preview media directly from the notification, then tap through to open the linked content.
+
+<p align="center">
+  <img src="https://cdn.activitysmith.com/features/rich-push-notification-with-audio.png" alt="Rich push notification with audio" width="680" />
+</p>
+
+What will work:
+
+- direct image URL: `.jpg`, `.png`, `.gif`, etc.
+- direct audio file URL: `.mp3`, `.m4a`, etc.
+- direct video file URL: `.mp4`, `.mov`, etc.
+- URL that responds with a proper media `Content-Type`, even if the path has no extension
+
+### Actionable Push Notifications
+
+<p align="center">
+  <img src="https://cdn.activitysmith.com/features/actionable-push-notifications-2.png" alt="Actionable push notification example" width="680" />
+</p>
+
+Actionable push notifications can open a URL on tap or trigger actions when someone long-presses the notification.
+Webhooks are executed by the ActivitySmith backend.
+
+```ruby
+activitysmith.notifications.send(
+  {
+    title: "New subscription 💸",
+    message: "Customer upgraded to Pro plan",
+    redirection: "https://crm.example.com/customers/cus_9f3a1d", # Optional
+    actions: [ # Optional (max 4)
+      {
+        title: "Open CRM Profile",
+        type: "open_url",
+        url: "https://crm.example.com/customers/cus_9f3a1d"
+      },
+      {
+        title: "Start Onboarding Workflow",
+        type: "webhook",
+        url: "https://hooks.example.com/activitysmith/onboarding/start",
+        method: "POST",
+        body: {
+          customer_id: "cus_9f3a1d",
+          plan: "pro"
+        }
+      }
+    ]
+  }
+)
 ```
 
 ## Live Activities
 
-Live Activities come in two UI types, but the lifecycle stays the same:
-start the activity, keep the returned `activity_id`, update it as state
-changes, then end it when the work is done.
+<p align="center">
+  <img src="https://cdn.activitysmith.com/features/metrics-live-activity-action.png" alt="Live Activities example" width="680" />
+</p>
+
+ActivitySmith supports two ways to drive Live Activities:
+
+- Recommended: stream updates with `activitysmith.live_activities.stream(...)`
+- Advanced: manual lifecycle control with `start`, `update`, and `end`
+
+Use stream updates when you want the easiest, stateless flow. You don't need to
+store `activity_id` or manage lifecycle state yourself. Send the latest state
+for a stable `stream_key` and ActivitySmith will start or update the Live
+Activity for you. When the tracked process is over, call `end_stream(...)`.
+
+Use the manual lifecycle methods when you need direct control over a specific
+Live Activity instance.
+
+Live Activity UI types:
+
+- `metrics`: best for live operational stats like server CPU and memory, queue depth, or replica lag
+- `segmented_progress`: best for step-based workflows like deployments, backups, and ETL pipelines
+- `progress`: best for continuous jobs like uploads, reindexes, and long-running migrations tracked as a percentage
+
+### Recommended: Stream updates
+
+Use a stable `stream_key` to identify the system or workflow you are tracking,
+such as a server, deployment, build pipeline, cron job, or charging session.
+This is especially useful for cron jobs and other scheduled tasks where you do
+not want to store `activity_id` between runs.
+
+#### Metrics
+
+<p align="center">
+  <img src="https://cdn.activitysmith.com/features/metrics-live-activity-start.png" alt="Metrics stream example" width="680" />
+</p>
+
+```ruby
+status = activitysmith.live_activities.stream(
+  "prod-web-1",
+  {
+    content_state: {
+      title: "Server Health",
+      subtitle: "prod-web-1",
+      type: "metrics",
+      metrics: [
+        { label: "CPU", value: 9, unit: "%" },
+        { label: "MEM", value: 45, unit: "%" }
+      ]
+    }
+  }
+)
+```
+
+#### Segmented progress
+
+<p align="center">
+  <img src="https://cdn.activitysmith.com/features/update-live-activity.png" alt="Segmented progress stream example" width="680" />
+</p>
+
+```ruby
+activitysmith.live_activities.stream(
+  "nightly-backup",
+  {
+    content_state: {
+      title: "Nightly Backup",
+      subtitle: "upload archive",
+      type: "segmented_progress",
+      number_of_steps: 3,
+      current_step: 2
+    }
+  }
+)
+```
+
+#### Progress
+
+<p align="center">
+  <img src="https://cdn.activitysmith.com/features/progress-live-activity.png" alt="Progress stream example" width="680" />
+</p>
+
+```ruby
+activitysmith.live_activities.stream(
+  "search-reindex",
+  {
+    content_state: {
+      title: "Search Reindex",
+      subtitle: "catalog-v2",
+      type: "progress",
+      percentage: 42
+    }
+  }
+)
+```
+
+Call `stream(...)` again with the same `stream_key` whenever the state changes.
+
+#### End a stream
+
+Use this when the tracked process is finished and you no longer want the Live
+Activity on devices. `content_state` is optional here; include it if you want
+to end the stream with a final state.
+
+```ruby
+activitysmith.live_activities.end_stream(
+  "prod-web-1",
+  {
+    content_state: {
+      title: "Server Health",
+      subtitle: "prod-web-1",
+      type: "metrics",
+      metrics: [
+        { label: "CPU", value: 7, unit: "%" },
+        { label: "MEM", value: 38, unit: "%" }
+      ]
+    }
+  }
+)
+```
+
+If you later send another `stream(...)` request with the same `stream_key`,
+ActivitySmith starts a new Live Activity for that stream again.
+
+Stream responses include an `operation` field:
 
-- `segmented_progress`: best for jobs tracked in steps
-- `progress`: best for jobs tracked as a percentage or numeric range
+- `started`: ActivitySmith started a new Live Activity for this `stream_key`
+- `updated`: ActivitySmith updated the current Live Activity
+- `rotated`: ActivitySmith ended the previous Live Activity and started a new one
+- `noop`: the incoming state matched the current state, so no update was sent
+- `paused`: the stream is paused, so no Live Activity was started or updated
+- `ended`: returned by `end_stream(...)` after the stream is ended
 
-### Shared flow
+### Advanced: Manual lifecycle control
+
+Use these methods when you want to manage the Live Activity lifecycle yourself.
+
+#### Shared flow
 
 1. Call `activitysmith.live_activities.start(...)`.
 2. Save the returned `activity_id`.
 3. Call `activitysmith.live_activities.update(...)` as progress changes.
 4. Call `activitysmith.live_activities.end(...)` when the work is finished.
 
+### Metrics Type
+
+Use `metrics` when you want to keep a small set of live stats visible, such as
+server health, queue pressure, or database load.
+
+#### Start
+
+<p align="center">
+  <img src="https://cdn.activitysmith.com/features/metrics-live-activity-start.png" alt="Metrics start example" width="680" />
+</p>
+
+```ruby
+start = activitysmith.live_activities.start(
+  {
+    content_state: {
+      title: "Server Health",
+      subtitle: "prod-web-1",
+      type: "metrics",
+      metrics: [
+        { label: "CPU", value: 9, unit: "%" },
+        { label: "MEM", value: 45, unit: "%" }
+      ]
+    }
+  }
+)
+
+activity_id = start.activity_id
+```
+
+#### Update
+
+<p align="center">
+  <img src="https://cdn.activitysmith.com/features/metrics-live-activity-update.png" alt="Metrics update example" width="680" />
+</p>
+
+```ruby
+activitysmith.live_activities.update(
+  {
+    activity_id: activity_id,
+    content_state: {
+      title: "Server Health",
+      subtitle: "prod-web-1",
+      type: "metrics",
+      metrics: [
+        { label: "CPU", value: 76, unit: "%" },
+        { label: "MEM", value: 52, unit: "%" }
+      ]
+    }
+  }
+)
+```
+
+#### End
+
+<p align="center">
+  <img src="https://cdn.activitysmith.com/features/metrics-live-activity-end.png" alt="Metrics end example" width="680" />
+</p>
+
+```ruby
+activitysmith.live_activities.end(
+  {
+    activity_id: activity_id,
+    content_state: {
+      title: "Server Health",
+      subtitle: "prod-web-1",
+      type: "metrics",
+      metrics: [
+        { label: "CPU", value: 7, unit: "%" },
+        { label: "MEM", value: 38, unit: "%" }
+      ],
+      auto_dismiss_minutes: 2
+    }
+  }
+)
+```
+
 ### Segmented Progress Type
 
 Use `segmented_progress` when progress is easier to follow as steps instead of a
 raw percentage. It fits jobs like backups, deployments, ETL pipelines, and
-checklists where "step 2 of 3" is more useful than "67%".
-`number_of_steps` is dynamic, so you can increase or decrease it later if the
-workflow changes.
+checklists where "step 2 of 3" is more useful than "67%". `number_of_steps` is
+dynamic, so you can increase or decrease it later if the workflow changes.
 
 #### Start
 
@@ -80,8 +346,7 @@ start = activitysmith.live_activities.start(
       current_step: 1,
       type: "segmented_progress",
       color: "yellow"
-    },
-    channels: ["devs", "ops"] # Optional
+    }
   }
 )
 
@@ -95,19 +360,17 @@ activity_id = start.activity_id
 </p>
 
 ```ruby
-update = activitysmith.live_activities.update(
+activitysmith.live_activities.update(
   {
     activity_id: activity_id,
     content_state: {
       title: "Nightly database backup",
       subtitle: "upload archive",
-      number_of_steps: 4,
+      number_of_steps: 3,
       current_step: 2
     }
   }
 )
-
-puts update.devices_notified
 ```
 
 #### End
@@ -117,20 +380,18 @@ puts update.devices_notified
 </p>
 
 ```ruby
-finish = activitysmith.live_activities.end(
+activitysmith.live_activities.end(
   {
     activity_id: activity_id,
     content_state: {
       title: "Nightly database backup",
       subtitle: "verify restore",
-      number_of_steps: 4,
-      current_step: 4,
+      number_of_steps: 3,
+      current_step: 3,
       auto_dismiss_minutes: 2
     }
   }
 )
-
-puts finish.success
 ```
 
 ### Progress Type
@@ -152,8 +413,7 @@ start = activitysmith.live_activities.start(
       title: "EV Charging",
       subtitle: "Added 30 mi range",
       type: "progress",
-      percentage: 15,
-      color: "lime"
+      percentage: 15
     }
   }
 )
@@ -200,78 +460,78 @@ activitysmith.live_activities.end(
 )
 ```
 
-## Channels
+### Live Activity Action
 
-Channels are used to target specific team members or devices. Can be used for both push notifications and live activities.
+Just like Actionable Push Notifications, Live Activities can have a button that opens a URL in a browser or triggers a webhook. Webhooks are executed by the ActivitySmith backend.
+
+<p align="center">
+  <img src="https://cdn.activitysmith.com/features/metrics-live-activity-action.png" alt="Metrics Live Activity with action" width="680" />
+</p>
+
+#### Open URL action
 
 ```ruby
-response = activitysmith.notifications.send(
+start = activitysmith.live_activities.start(
   {
-    title: "New subscription 💸",
-    message: "Customer upgraded to Pro plan",
-    channels: ["sales", "customer-success"] # Optional
+    content_state: {
+      title: "Server Health",
+      subtitle: "prod-web-1",
+      type: "metrics",
+      metrics: [
+        { label: "CPU", value: 76, unit: "%" },
+        { label: "MEM", value: 52, unit: "%" }
+      ]
+    },
+    action: {
+      title: "Open Dashboard",
+      type: "open_url",
+      url: "https://ops.example.com/servers/prod-web-1"
+    }
   }
 )
+
+activity_id = start.activity_id
 ```
 
-## Rich Push Notifications with Media
-
-<p align="center">
-  <img src="https://cdn.activitysmith.com/features/rich-push-notification-with-image.png" alt="Rich push notification with image" width="680" />
-</p>
+#### Webhook action
 
 ```ruby
-response = activitysmith.notifications.send(
+activitysmith.live_activities.update(
   {
-    title: "Homepage ready",
-    message: "Your agent finished the redesign.",
-    media: "https://cdn.example.com/output/homepage-v2.png",
-    redirection: "https://github.com/acme/web/pull/482"
+    activity_id: activity_id,
+    content_state: {
+      title: "Server Health",
+      subtitle: "prod-web-1",
+      type: "metrics",
+      metrics: [
+        { label: "CPU", value: 91, unit: "%" },
+        { label: "MEM", value: 57, unit: "%" }
+      ]
+    },
+    action: {
+      title: "Restart Service",
+      type: "webhook",
+      url: "https://ops.example.com/hooks/servers/prod-web-1/restart",
+      method: "POST",
+      body: {
+        server_id: "prod-web-1",
+        requested_by: "activitysmith-ruby"
+      }
+    }
   }
 )
 ```
 
-Send images, videos, or audio with your push notifications, press and hold to preview media directly from the notification, then tap through to open the linked content.
-
-<p align="center">
-  <img src="https://cdn.activitysmith.com/features/rich-push-notification-with-audio.png" alt="Rich push notification with audio" width="680" />
-</p>
-
-What will work:
-
-- direct image URL: `.jpg`, `.png`, `.gif`, etc.
-- direct audio file URL: `.mp3`, `.m4a`, etc.
-- direct video file URL: `.mp4`, `.mov`, etc.
-- URL that responds with a proper media `Content-Type`, even if the path has no extension
-
-## Push Notification Redirection and Actions
+## Channels
 
-Push notification redirection and actions are optional and can be used to redirect the user to a specific URL when they tap the notification or to trigger a specific action when they long-press the notification.
-Webhooks are executed by ActivitySmith backend.
+Channels are used to target specific team members or devices. Can be used for both push notifications and live activities.
 
 ```ruby
-response = activitysmith.notifications.send(
+activitysmith.notifications.send(
   {
     title: "New subscription 💸",
     message: "Customer upgraded to Pro plan",
-    redirection: "https://crm.example.com/customers/cus_9f3a1d", # Optional
-    actions: [ # Optional (max 4)
-      {
-        title: "Open CRM Profile",
-        type: "open_url",
-        url: "https://crm.example.com/customers/cus_9f3a1d"
-      },
-      {
-        title: "Start Onboarding Workflow",
-        type: "webhook",
-        url: "https://hooks.example.com/activitysmith/onboarding/start",
-        method: "POST",
-        body: {
-          customer_id: "cus_9f3a1d",
-          plan: "pro"
-        }
-      }
-    ]
+    channels: ["sales", "customer-success"] # Optional
   }
 )
 ```