From 3c1a1cf47ee1dd679ae02df5c0b94d58ebb89048 Mon Sep 17 00:00:00 2001
From: bardonadam <bardon.adam@gmail.com>
Date: Sat, 7 Feb 2026 10:44:14 +0100
Subject: [PATCH] docs: improve README examples and structure

---
 README.md | 94 ++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 76 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 1eedb28..c49489d 100644
--- a/README.md
+++ b/README.md
@@ -12,9 +12,7 @@ See [API reference](https://activitysmith.com/docs/api-reference/introduction)
 npm install activitysmith
 ```
 
-## Usage
-
-ESM:
+## Setup
 
 ```ts
 import ActivitySmith from "activitysmith";
@@ -22,16 +20,6 @@ import ActivitySmith from "activitysmith";
 const activitysmith = new ActivitySmith({
   apiKey: process.env.ACTIVITYSMITH_API_KEY,
 });
-
-// Push Notifications
-await activitysmith.notifications.send({
-  // See PushNotificationRequest for fields
-});
-
-// Live Activities
-await activitysmith.liveActivities.start({
-  // See LiveActivityStartRequest for fields
-});
 ```
 
 CommonJS:
@@ -44,14 +32,84 @@ const activitysmith = new ActivitySmith({
 });
 ```
 
-## API Surface
+## Usage
 
-The client exposes grouped resources:
+### Send a Push Notification
 
-- `activitysmith.liveActivities`
-- `activitysmith.notifications`
+```ts
+const response = await activitysmith.notifications.send({
+  title: "Build Failed",
+  message: "CI pipeline failed on main branch",
+});
+
+console.log(response.success);
+console.log(response.devices_notified);
+```
+
+### Start a Live Activity
+
+```ts
+const start = await activitysmith.liveActivities.start({
+  content_state: {
+    title: "ActivitySmith API Deployment",
+    subtitle: "start",
+    number_of_steps: 4,
+    current_step: 1,
+    type: "segmented_progress",
+    color: "yellow",
+  },
+});
+
+const activityId = start.activity_id;
+```
 
-Each method is fully typed. Request and response types are included in the type definitions.
+### Update a Live Activity
+
+```ts
+const update = await activitysmith.liveActivities.update({
+  activity_id: activityId,
+  content_state: {
+    title: "ActivitySmith API Deployment",
+    subtitle: "npm i & pm2",
+    current_step: 3,
+  },
+});
+
+console.log(update.devices_notified);
+```
+
+### End a Live Activity
+
+```ts
+const end = await activitysmith.liveActivities.end({
+  activity_id: activityId,
+  content_state: {
+    title: "ActivitySmith API Deployment",
+    subtitle: "done",
+    current_step: 4,
+    auto_dismiss_minutes: 3,
+  },
+});
+
+console.log(end.success);
+```
+
+## Error Handling
+
+```ts
+try {
+  await activitysmith.notifications.send({
+    title: "Build Failed",
+  });
+} catch (error) {
+  console.error(error);
+}
+```
+
+## API Surface
+
+- `activitysmith.notifications`
+- `activitysmith.liveActivities`
 
 ## TypeScript Support