From 861fe239479fd4684459c1d4b79f2ba1d5e0338f Mon Sep 17 00:00:00 2001
From: activitysmith-bot <activitysmith-bot@users.noreply.github.com>
Date: Tue, 15 Sep 2026 12:49:01 +0000
Subject: [PATCH 01/12] chore: regenerate SDK

---
 generated/apis/AppIconBadgesApi.ts |   3 +-
 generated/apis/PublicApi.ts        |  96 ++++++++
 generated/apis/index.ts            |   1 +
 generated/models/index.ts          | 366 ++++++++++++++++++++++++++++-
 generated/openapi-source.json      |   6 +
 5 files changed, 464 insertions(+), 8 deletions(-)
 create mode 100644 generated/apis/PublicApi.ts
 create mode 100644 generated/openapi-source.json

diff --git a/generated/apis/AppIconBadgesApi.ts b/generated/apis/AppIconBadgesApi.ts
index 3346b05..0456e22 100644
--- a/generated/apis/AppIconBadgesApi.ts
+++ b/generated/apis/AppIconBadgesApi.ts
@@ -15,12 +15,13 @@
 
 import * as runtime from '../runtime';
 import type {
+  AppIconBadgeCountUpdateError,
   AppIconBadgeCountUpdateRequest,
   AppIconBadgeCountUpdateResponse,
   BadRequestError,
   ForbiddenError,
-  NoRecipientsError,
   RateLimitError,
+  UpdateAppIconBadgeCount422Response,
 } from '../models/index';
 
 export interface UpdateAppIconBadgeCountRequest {
diff --git a/generated/apis/PublicApi.ts b/generated/apis/PublicApi.ts
new file mode 100644
index 0000000..32cbc37
--- /dev/null
+++ b/generated/apis/PublicApi.ts
@@ -0,0 +1,96 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * ActivitySmith API
+ * Send push notifications and Live Activities to your own devices via a single API key.
+ *
+ * The version of the OpenAPI document: 1.0.0
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+
+import * as runtime from '../runtime';
+import type {
+  ChangelogListResponse,
+  HealthResponse,
+} from '../models/index';
+
+export interface ListPublicChangelogEntriesRequest {
+    platform?: string;
+    limit?: number;
+}
+
+/**
+ * 
+ */
+export class PublicApi extends runtime.BaseAPI {
+
+    /**
+     * Returns the current availability of the ActivitySmith API and its required services. No authentication is required.
+     * Get API Health
+     */
+    async getApiHealthRaw(initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<HealthResponse>> {
+        const queryParameters: any = {};
+
+        const headerParameters: runtime.HTTPHeaders = {};
+
+        const response = await this.request({
+            path: `/health`,
+            method: 'GET',
+            headers: headerParameters,
+            query: queryParameters,
+        }, initOverrides);
+
+        return new runtime.JSONApiResponse(response);
+    }
+
+    /**
+     * Returns the current availability of the ActivitySmith API and its required services. No authentication is required.
+     * Get API Health
+     */
+    async getApiHealth(initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<HealthResponse> {
+        const response = await this.getApiHealthRaw(initOverrides);
+        return await response.value();
+    }
+
+    /**
+     * Returns published ActivitySmith app changelog entries. No authentication is required.
+     * List Public Changelog Entries
+     */
+    async listPublicChangelogEntriesRaw(requestParameters: ListPublicChangelogEntriesRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ChangelogListResponse>> {
+        const queryParameters: any = {};
+
+        if (requestParameters['platform'] != null) {
+            queryParameters['platform'] = requestParameters['platform'];
+        }
+
+        if (requestParameters['limit'] != null) {
+            queryParameters['limit'] = requestParameters['limit'];
+        }
+
+        const headerParameters: runtime.HTTPHeaders = {};
+
+        const response = await this.request({
+            path: `/changelog`,
+            method: 'GET',
+            headers: headerParameters,
+            query: queryParameters,
+        }, initOverrides);
+
+        return new runtime.JSONApiResponse(response);
+    }
+
+    /**
+     * Returns published ActivitySmith app changelog entries. No authentication is required.
+     * List Public Changelog Entries
+     */
+    async listPublicChangelogEntries(requestParameters: ListPublicChangelogEntriesRequest = {}, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ChangelogListResponse> {
+        const response = await this.listPublicChangelogEntriesRaw(requestParameters, initOverrides);
+        return await response.value();
+    }
+
+}
diff --git a/generated/apis/index.ts b/generated/apis/index.ts
index ecb06b5..b74c2df 100644
--- a/generated/apis/index.ts
+++ b/generated/apis/index.ts
@@ -3,4 +3,5 @@
 export * from './AppIconBadgesApi';
 export * from './LiveActivitiesApi';
 export * from './MetricsApi';
+export * from './PublicApi';
 export * from './PushNotificationsApi';
diff --git a/generated/models/index.ts b/generated/models/index.ts
index 0572d22..eb6b708 100644
--- a/generated/models/index.ts
+++ b/generated/models/index.ts
@@ -75,6 +75,79 @@ export interface AlertPayload {
      */
     body?: string;
 }
+/**
+ * 
+ * @export
+ * @interface AppIconBadgeCountUpdateError
+ */
+export interface AppIconBadgeCountUpdateError {
+    /**
+     * 
+     * @type {string}
+     * @memberof AppIconBadgeCountUpdateError
+     */
+    error: string;
+    /**
+     * 
+     * @type {string}
+     * @memberof AppIconBadgeCountUpdateError
+     */
+    code: AppIconBadgeCountUpdateErrorCodeEnum;
+    /**
+     * 
+     * @type {string}
+     * @memberof AppIconBadgeCountUpdateError
+     */
+    message: string;
+    /**
+     * 
+     * @type {number}
+     * @memberof AppIconBadgeCountUpdateError
+     */
+    badge: number;
+    /**
+     * 
+     * @type {number}
+     * @memberof AppIconBadgeCountUpdateError
+     */
+    devices_targeted?: number;
+    /**
+     * 
+     * @type {number}
+     * @memberof AppIconBadgeCountUpdateError
+     */
+    devices_updated: number;
+    /**
+     * 
+     * @type {number}
+     * @memberof AppIconBadgeCountUpdateError
+     */
+    users_updated?: number;
+    /**
+     * Deprecated compatibility alias for devices_updated.
+     * @type {number}
+     * @memberof AppIconBadgeCountUpdateError
+     * @deprecated
+     */
+    devices_notified?: number;
+    /**
+     * 
+     * @type {Array<string>}
+     * @memberof AppIconBadgeCountUpdateError
+     */
+    effective_channel_slugs?: Array<string>;
+}
+
+
+/**
+ * @export
+ */
+export const AppIconBadgeCountUpdateErrorCodeEnum = {
+    DeviceDisconnected: 'badge_device_disconnected',
+    UpdateFailed: 'badge_update_failed'
+} as const;
+export type AppIconBadgeCountUpdateErrorCodeEnum = typeof AppIconBadgeCountUpdateErrorCodeEnum[keyof typeof AppIconBadgeCountUpdateErrorCodeEnum];
+
 /**
  * 
  * @export
@@ -113,17 +186,31 @@ export interface AppIconBadgeCountUpdateResponse {
      */
     badge: number;
     /**
-     * 
+     * Number of devices whose App Icon Badge Count was updated.
      * @type {number}
      * @memberof AppIconBadgeCountUpdateResponse
      */
-    devices_notified: number;
+    devices_updated: number;
     /**
-     * 
+     * Number of account users with at least one updated device.
+     * @type {number}
+     * @memberof AppIconBadgeCountUpdateResponse
+     */
+    users_updated: number;
+    /**
+     * Deprecated compatibility alias for devices_updated.
+     * @type {number}
+     * @memberof AppIconBadgeCountUpdateResponse
+     * @deprecated
+     */
+    devices_notified?: number;
+    /**
+     * Deprecated compatibility alias for users_updated.
      * @type {number}
      * @memberof AppIconBadgeCountUpdateResponse
+     * @deprecated
      */
-    users_notified: number;
+    users_notified?: number;
     /**
      * 
      * @type {Array<string>}
@@ -156,6 +243,117 @@ export interface BadRequestError {
      */
     message: string;
 }
+/**
+ * 
+ * @export
+ * @interface ChangelogEntry
+ */
+export interface ChangelogEntry {
+    /**
+     * 
+     * @type {string}
+     * @memberof ChangelogEntry
+     */
+    id: string;
+    /**
+     * 
+     * @type {string}
+     * @memberof ChangelogEntry
+     */
+    platform: string;
+    /**
+     * 
+     * @type {string}
+     * @memberof ChangelogEntry
+     */
+    version: string;
+    /**
+     * 
+     * @type {string}
+     * @memberof ChangelogEntry
+     */
+    title: string;
+    /**
+     * 
+     * @type {string}
+     * @memberof ChangelogEntry
+     */
+    subtitle: string | null;
+    /**
+     * 
+     * @type {string}
+     * @memberof ChangelogEntry
+     */
+    hero_image_url: string | null;
+    /**
+     * 
+     * @type {string}
+     * @memberof ChangelogEntry
+     */
+    cta_title: string;
+    /**
+     * 
+     * @type {string}
+     * @memberof ChangelogEntry
+     */
+    published_at: string | null;
+    /**
+     * 
+     * @type {Array<ChangelogItem>}
+     * @memberof ChangelogEntry
+     */
+    items: Array<ChangelogItem>;
+}
+/**
+ * 
+ * @export
+ * @interface ChangelogItem
+ */
+export interface ChangelogItem {
+    /**
+     * 
+     * @type {string}
+     * @memberof ChangelogItem
+     */
+    icon?: string | null;
+    /**
+     * 
+     * @type {string}
+     * @memberof ChangelogItem
+     */
+    title: string;
+    /**
+     * 
+     * @type {string}
+     * @memberof ChangelogItem
+     */
+    body: string;
+    /**
+     * 
+     * @type {string}
+     * @memberof ChangelogItem
+     */
+    image_url?: string | null;
+    /**
+     * 
+     * @type {string}
+     * @memberof ChangelogItem
+     */
+    accent_color?: string | null;
+}
+/**
+ * 
+ * @export
+ * @interface ChangelogListResponse
+ */
+export interface ChangelogListResponse {
+    /**
+     * 
+     * @type {Array<ChangelogEntry>}
+     * @memberof ChangelogListResponse
+     */
+    changelogs: Array<ChangelogEntry>;
+}
 /**
  * 
  * @export
@@ -737,6 +935,82 @@ export interface ForbiddenError {
      */
     message: string;
 }
+/**
+ * 
+ * @export
+ * @interface HealthCheck
+ */
+export interface HealthCheck {
+    /**
+     * 
+     * @type {string}
+     * @memberof HealthCheck
+     */
+    name: HealthCheckNameEnum;
+    /**
+     * 
+     * @type {string}
+     * @memberof HealthCheck
+     */
+    status: HealthCheckStatusEnum;
+    /**
+     * 
+     * @type {number}
+     * @memberof HealthCheck
+     */
+    duration_ms: number;
+}
+
+
+/**
+ * @export
+ */
+export const HealthCheckNameEnum = {
+    Database: 'database',
+    Redis: 'redis'
+} as const;
+export type HealthCheckNameEnum = typeof HealthCheckNameEnum[keyof typeof HealthCheckNameEnum];
+
+/**
+ * @export
+ */
+export const HealthCheckStatusEnum = {
+    Ok: 'ok',
+    Failed: 'failed'
+} as const;
+export type HealthCheckStatusEnum = typeof HealthCheckStatusEnum[keyof typeof HealthCheckStatusEnum];
+
+/**
+ * 
+ * @export
+ * @interface HealthResponse
+ */
+export interface HealthResponse {
+    /**
+     * 
+     * @type {boolean}
+     * @memberof HealthResponse
+     */
+    ok: boolean;
+    /**
+     * 
+     * @type {string}
+     * @memberof HealthResponse
+     */
+    service: string;
+    /**
+     * 
+     * @type {string}
+     * @memberof HealthResponse
+     */
+    timestamp: string;
+    /**
+     * 
+     * @type {Array<HealthCheck>}
+     * @memberof HealthResponse
+     */
+    checks: Array<HealthCheck>;
+}
 /**
  * Optional action button shown in the Live Activity UI. Use action for the primary button, or secondary_action for a secondary button on alert, progress, and segmented_progress Live Activities.
  * @export
@@ -849,12 +1123,24 @@ export type LiveActivityColor = typeof LiveActivityColor[keyof typeof LiveActivi
  * @interface LiveActivityEndRequest
  */
 export interface LiveActivityEndRequest {
+    /**
+     * Additional information shown in notification and Live Activity details in ActivitySmith. Not displayed in the Push Notification or Live Activity on the device. Values must be strings, finite numbers, or booleans. At most 50 entries and 16 KB of serialized UTF-8 JSON. Omit on updates to preserve existing Metadata; send {} to clear it.
+     * @type {{ [key: string]: MetadataValue; }}
+     * @memberof LiveActivityEndRequest
+     */
+    metadata?: { [key: string]: MetadataValue; };
     /**
      * 
      * @type {string}
      * @memberof LiveActivityEndRequest
      */
     activity_id: string;
+    /**
+     * Tags for notification history. Omit to keep existing Tags, supply an array to replace them, or send an empty array to clear them.
+     * @type {Array<string>}
+     * @memberof LiveActivityEndRequest
+     */
+    tags?: Array<string>;
     /**
      * 
      * @type {ContentStateEnd}
@@ -936,11 +1222,23 @@ export interface LiveActivityLimitError {
      */
     limit: number;
     /**
-     * Current number of active Live Activities.
+     * Highest number of active Live Activities among the targeted devices.
      * @type {number}
      * @memberof LiveActivityLimitError
      */
     active: number;
+    /**
+     * Number of targeted devices that have reached the enforced iOS Live Activity concurrency threshold. Included only when targeted devices have mixed capacity.
+     * @type {number}
+     * @memberof LiveActivityLimitError
+     */
+    blocked_devices?: number;
+    /**
+     * Total number of targeted devices. Included only when targeted devices have mixed capacity.
+     * @type {number}
+     * @memberof LiveActivityLimitError
+     */
+    targeted_devices?: number;
 }
 /**
  * Start a new Live Activity. The response includes activity_id for later update and end calls.
@@ -948,6 +1246,12 @@ export interface LiveActivityLimitError {
  * @interface LiveActivityStartRequest
  */
 export interface LiveActivityStartRequest {
+    /**
+     * Additional information shown in notification and Live Activity details in ActivitySmith. Not displayed in the Push Notification or Live Activity on the device. Values must be strings, finite numbers, or booleans. At most 50 entries and 16 KB of serialized UTF-8 JSON. Omit on updates to preserve existing Metadata; send {} to clear it.
+     * @type {{ [key: string]: MetadataValue; }}
+     * @memberof LiveActivityStartRequest
+     */
+    metadata?: { [key: string]: MetadataValue; };
     /**
      * 
      * @type {ContentStateStart}
@@ -1040,6 +1344,18 @@ export interface LiveActivityStartResponse {
  * @interface LiveActivityStreamDeleteRequest
  */
 export interface LiveActivityStreamDeleteRequest {
+    /**
+     * Additional information shown in notification and Live Activity details in ActivitySmith. Not displayed in the Push Notification or Live Activity on the device. Values must be strings, finite numbers, or booleans. At most 50 entries and 16 KB of serialized UTF-8 JSON. Omit on updates to preserve existing Metadata; send {} to clear it.
+     * @type {{ [key: string]: MetadataValue; }}
+     * @memberof LiveActivityStreamDeleteRequest
+     */
+    metadata?: { [key: string]: MetadataValue; };
+    /**
+     * Optional tags to organize and filter notification history.
+     * @type {Array<string>}
+     * @memberof LiveActivityStreamDeleteRequest
+     */
+    tags?: Array<string>;
     /**
      * 
      * @type {StreamContentState}
@@ -1217,6 +1533,12 @@ export type LiveActivityStreamPutResponseOperationEnum = typeof LiveActivityStre
  * @interface LiveActivityStreamRequest
  */
 export interface LiveActivityStreamRequest {
+    /**
+     * Additional information shown in notification and Live Activity details in ActivitySmith. Not displayed in the Push Notification or Live Activity on the device. Values must be strings, finite numbers, or booleans. At most 50 entries and 16 KB of serialized UTF-8 JSON. Omit on updates to preserve existing Metadata; send {} to clear it.
+     * @type {{ [key: string]: MetadataValue; }}
+     * @memberof LiveActivityStreamRequest
+     */
+    metadata?: { [key: string]: MetadataValue; };
     /**
      * 
      * @type {StreamContentState}
@@ -1266,12 +1588,24 @@ export interface LiveActivityStreamRequest {
  * @interface LiveActivityUpdateRequest
  */
 export interface LiveActivityUpdateRequest {
+    /**
+     * Additional information shown in notification and Live Activity details in ActivitySmith. Not displayed in the Push Notification or Live Activity on the device. Values must be strings, finite numbers, or booleans. At most 50 entries and 16 KB of serialized UTF-8 JSON. Omit on updates to preserve existing Metadata; send {} to clear it.
+     * @type {{ [key: string]: MetadataValue; }}
+     * @memberof LiveActivityUpdateRequest
+     */
+    metadata?: { [key: string]: MetadataValue; };
     /**
      * 
      * @type {string}
      * @memberof LiveActivityUpdateRequest
      */
     activity_id: string;
+    /**
+     * Tags for notification history. Omit to keep existing Tags, supply an array to replace them, or send an empty array to clear them.
+     * @type {Array<string>}
+     * @memberof LiveActivityUpdateRequest
+     */
+    tags?: Array<string>;
     /**
      * 
      * @type {ContentStateUpdate}
@@ -1339,6 +1673,12 @@ export const LiveActivityWebhookMethod = {
 } as const;
 export type LiveActivityWebhookMethod = typeof LiveActivityWebhookMethod[keyof typeof LiveActivityWebhookMethod];
 
+/**
+ * @type MetadataValue
+ * 
+ * @export
+ */
+export type MetadataValue = boolean | number | string;
 /**
  * 
  * @export
@@ -1460,7 +1800,7 @@ export interface PushNotificationAction {
      */
     type: PushNotificationActionType;
     /**
-     * Action URL. For open_url, use an HTTP or HTTPS URL or a shortcuts://run-shortcut?name=... URL that runs a specific iPhone Shortcut. For webhook, use an HTTPS URL called by the ActivitySmith backend.
+     * Action URL. For open_url, use HTTP, HTTPS, Shortcuts, or an installed app’s custom URL scheme, such as spotify:// or spotify:track:123. Custom app schemes require iOS 1.13.4 build 2 or later; no web fallback is provided. Internal and executable schemes are blocked. For webhook, use an HTTPS URL called by the ActivitySmith backend.
      * @type {string}
      * @memberof PushNotificationAction
      */
@@ -1496,6 +1836,12 @@ export type PushNotificationActionType = typeof PushNotificationActionType[keyof
  */
 export interface PushNotificationRequest {
     [key: string]: any | any;
+    /**
+     * Additional information shown in notification and Live Activity details in ActivitySmith. Not displayed in the Push Notification or Live Activity on the device. Values must be strings, finite numbers, or booleans. At most 50 entries and 16 KB of serialized UTF-8 JSON. Omit on updates to preserve existing Metadata; send {} to clear it.
+     * @type {{ [key: string]: MetadataValue; }}
+     * @memberof PushNotificationRequest
+     */
+    metadata?: { [key: string]: MetadataValue; };
     /**
      * 
      * @type {string}
@@ -1521,7 +1867,7 @@ export interface PushNotificationRequest {
      */
     media?: string;
     /**
-     * Optional HTTP URL, HTTPS URL, or shortcuts://run-shortcut?name=... URL opened when the user taps the notification body. Use shortcuts://run-shortcut?name=... to run a specific iPhone Shortcut that already exists on the user's device. Overrides the default tap target from `media` when both are provided.
+     * Optional HTTP, HTTPS, Shortcuts, or installed app URL opened when the user taps the notification body. Custom schemes such as spotify:// and spotify:track:123 require iOS 1.13.4 build 2 or later and an installed handler; no web fallback is provided. Internal and executable schemes are blocked. Overrides the default tap target from media.
      * @type {string}
      * @memberof PushNotificationRequest
      */
@@ -1835,3 +2181,9 @@ export const StreamContentStateStepColorsEnum = {
 } as const;
 export type StreamContentStateStepColorsEnum = typeof StreamContentStateStepColorsEnum[keyof typeof StreamContentStateStepColorsEnum];
 
+/**
+ * @type UpdateAppIconBadgeCount422Response
+ * 
+ * @export
+ */
+export type UpdateAppIconBadgeCount422Response = AppIconBadgeCountUpdateError | NoRecipientsError;
diff --git a/generated/openapi-source.json b/generated/openapi-source.json
new file mode 100644
index 0000000..5a616d3
--- /dev/null
+++ b/generated/openapi-source.json
@@ -0,0 +1,6 @@
+{
+  "repository": "ActivitySmithHQ/activitysmith-backend",
+  "commit": "3cd1df5f1296777bacfad731eac9f91d27d01c6e",
+  "path": "openapi.json",
+  "sha256": "e112ddb9a069dc0ad87a123d0be1286ff0a671da505fabfdf4bb94ff6bcb444f"
+}

From 33a75e02b31385fe8bbe26f4fe99b0a3e2c3f0e2 Mon Sep 17 00:00:00 2001
From: bardonadam <adam@initsignal.com>
Date: Tue, 15 Sep 2026 19:55:00 +0700
Subject: [PATCH 02/12] feat: prepare node SDK metadata and documentation
 updates

Preserve native metadata values and clearing semantics, extend legacy and stream-end history fields, and align the README with the pending SDK documentation. Package versions remain unchanged; release requires separate approval.

Verification: local SDK tests passed against the regenerated contract; README code-fence preservation check passed.

Initiated-by: user

Implemented-by: codex
---
 CHANGELOG.md            |  10 +
 README.md               | 402 +++++++++++++++++++---------------------
 src/ActivitySmith.ts    |  27 ++-
 tests/resources.test.js |  70 +++++++
 tests/smoke.test.js     |  31 ++++
 5 files changed, 327 insertions(+), 213 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0118f44..33d5dc4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,13 @@
+## Unreleased
+
+- Support Push Notification app deep links and final Tags/Metadata when ending a managed Live Activity stream.
+
+- Add Metadata to Push Notifications and Live Activity start, update, end, and stream requests, including empty-object clearing.
+
+- Add Tags replacement and empty-array clearing to legacy Live Activity update and end.
+
+- Add the optional SDK identity override from local commit `8bf44fc` so official wrappers such as the CLI can report their own `X-ActivitySmith-SDK` value. Include this in the next published Node SDK release.
+
 ## 1.10.0
 
 ### New Features
diff --git a/README.md b/README.md
index 7da79bb..6099457 100644
--- a/README.md
+++ b/README.md
@@ -1,50 +1,22 @@
-# ActivitySmith Node SDK
+# ActivitySmith Node.js SDK
 
-The ActivitySmith Node SDK provides convenient access to the ActivitySmith API from server-side JavaScript and TypeScript applications.
-
-## Documentation
-
-See [API reference](https://activitysmith.com/docs/api-reference/introduction)
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Setup](#setup)
-- [Push Notifications](#push-notifications)
-  - [Send a Push Notification](#send-a-push-notification)
-  - [Rich Push Notifications with Media](#rich-push-notifications-with-media)
-  - [Actionable Push Notifications](#actionable-push-notifications)
-- [Live Activities](#live-activities)
-  - [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)
-- [Widgets](#widgets)
-- [App Icon Badge Count](#app-icon-badge-count)
-- [Channels](#channels)
-- [Tags](#tags)
+[Documentation](https://activitysmith.com/docs/sdks/node)
 
 ## Installation
 
-```sh
+Install the ActivitySmith Node.js SDK with npm:
+
+```bash
 npm install activitysmith
 ```
 
-## Setup
-
-```ts
-import ActivitySmith from "activitysmith";
-
-const activitysmith = new ActivitySmith({
-  apiKey: process.env.ACTIVITYSMITH_API_KEY,
-});
-```
+## Quickstart
 
-CommonJS:
+1. [Create an API key](https://activitysmith.com/app/keys)
+2. Set `ACTIVITYSMITH_API_KEY` or pass `apiKey` when creating the client.
 
 ```js
-const ActivitySmith = require("activitysmith");
+import ActivitySmith from "activitysmith";
 
 const activitysmith = new ActivitySmith({
   apiKey: process.env.ACTIVITYSMITH_API_KEY,
@@ -55,11 +27,11 @@ const activitysmith = new ActivitySmith({
 
 ### Send a Push Notification
 
-<p align="center">
-  <img src="https://cdn.activitysmith.com/features/new-subscription-push-notification.png" alt="Push notification example" width="680" />
-</p>
+Send an immediate notification for a completed task or event.
 
-```ts
+![Push Notification example for a new subscription event](https://cdn.activitysmith.com/features/new-subscription-push-notification.png)
+
+```js
 await activitysmith.notifications.send({
   title: "New subscription 💸",
   message: "Customer upgraded to Pro plan",
@@ -68,24 +40,19 @@ await activitysmith.notifications.send({
 
 ### 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>
+![Rich Push Notification with image](https://cdn.activitysmith.com/features/rich-push-notification-with-image.png)
 
-```ts
+```js
 await 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.
+Attach images, videos, or audio to your Push Notifications. Press and hold the notification to preview the media.
 
-<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>
+![Rich Push Notification with audio](https://cdn.activitysmith.com/features/rich-push-notification-with-audio.png)
 
 What will work:
 
@@ -94,23 +61,33 @@ What will work:
 - direct video file URL: `.mp4`, `.mov`, etc.
 - URL that responds with a proper media `Content-Type`, even if the path has no extension
 
+`media` cannot be combined with `actions`.
+
+### Push Notifications with Redirection
+
+Open a web page, an iPhone Shortcut, or an installed app when someone taps the notification. Set `redirection` to an HTTP, HTTPS, or Shortcuts URL, or an app deep link such as `spotify:track:123`.
+
+```js
+await activitysmith.notifications.send({
+  title: "Homepage ready",
+  message: "Your agent finished the redesign.",
+  redirection: "https://github.com/acme/web/pull/482",
+});
+```
+
 ### 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 Notification with redirection and actions](https://cdn.activitysmith.com/features/actionable-push-notifications-2.png)
 
-Push notification `redirection` and `actions` are optional. Use them to open HTTPS URLs, run a specific iPhone Shortcut with `shortcuts://run-shortcut?name=...`, or trigger backend webhook workflows.
-Webhooks are executed by the ActivitySmith backend.
+For expanded notification actions, `open_url` supports HTTP, HTTPS, Shortcuts, and installed app deep links. Webhooks are executed by the ActivitySmith backend and must use HTTPS. Custom app links require iOS 1.13.4 build 2 or later and an installed app that handles the URL.
 
-```ts
+```js
 await activitysmith.notifications.send({
   title: "New subscription 💸",
   message: "Customer upgraded to Pro plan",
-  redirection: "https://crm.example.com/customers/cus_9f3a1d", // Optional
   actions: [
     {
-      title: "Open CRM Profile",
+      title: "Open CRM",
       type: "open_url",
       url: "https://crm.example.com/customers/cus_9f3a1d",
     },
@@ -129,20 +106,25 @@ await activitysmith.notifications.send({
         plan: "pro",
       },
     },
-  ], // Optional (max 4)
+  ],
 });
 ```
 
 ## Live Activities
 
-There are six types of Live Activities:
+Choose the Live Activity type that matches what you want to show:
+
+- ![Stats Live Activity with six labeled sales metrics](https://cdn.activitysmith.com/features/stats-live-activity.png) **Stats**: Show up to 8 labeled values on your Lock Screen, from revenue and orders to uptime and conversion.
 
-- `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
-- `timer`: best for countdowns and elapsed runtime, like benchmark runs, uploads, backups, transcodes, and long-running jobs
+- ![Metrics Live Activity with CPU and memory values](https://cdn.activitysmith.com/features/metrics-live-activity-start.png) **Metrics**: Track two related values with segmented bars, such as CPU and memory.
+
+- ![Segmented Progress Live Activity showing a workflow step](https://cdn.activitysmith.com/features/update-live-activity.png) **Segmented Progress**: Show progress through a known set of steps, like build, test, deploy, and verify.
+
+- ![Progress Live Activity showing percentage completion](https://cdn.activitysmith.com/features/progress-live-activity.png) **Progress**: Show percentage progress for jobs that move continuously toward completion.
+
+- ![Alert Live Activity showing a customer reactivation update](https://cdn.activitysmith.com/features/alert-live-activity.png) **Alert**: Show status updates with a clear message, badge, and icon. When you add an action button, `color` controls the button tint.
+
+- ![Timer Live Activity showing a benchmark run countdown](https://cdn.activitysmith.com/features/timer-live-activity.png) **Timer**: Count down from a duration, or count up from 00:00 while a job runs.
 
 ### Start & Update Live Activity
 
@@ -150,9 +132,7 @@ Use a stable `streamKey` to identify the metric, job, deployment, or system you
 
 #### Stats
 
-<p align="center">
-  <img src="https://cdn.activitysmith.com/features/stats-live-activity.png" alt="Stats Live Activity stream example" width="680" />
-</p>
+![Stats Live Activity stream example](https://cdn.activitysmith.com/features/stats-live-activity.png)
 
 ```ts
 await activitysmith.liveActivities.stream("sales-hourly", {
@@ -174,9 +154,7 @@ await activitysmith.liveActivities.stream("sales-hourly", {
 
 #### Metrics
 
-<p align="center">
-  <img src="https://cdn.activitysmith.com/features/metrics-live-activity-start.png" alt="Metrics Live Activity stream example" width="680" />
-</p>
+![Metrics Live Activity stream example](https://cdn.activitysmith.com/features/metrics-live-activity-start.png)
 
 ```ts
 await activitysmith.liveActivities.stream("prod-web-1", {
@@ -194,9 +172,7 @@ await activitysmith.liveActivities.stream("prod-web-1", {
 
 #### Segmented Progress
 
-<p align="center">
-  <img src="https://cdn.activitysmith.com/features/update-live-activity.png" alt="Segmented Progress Live Activity stream example" width="680" />
-</p>
+![Segmented Progress Live Activity stream example](https://cdn.activitysmith.com/features/update-live-activity.png)
 
 ```ts
 await activitysmith.liveActivities.stream("nightly-backup", {
@@ -212,9 +188,7 @@ await activitysmith.liveActivities.stream("nightly-backup", {
 
 #### Progress
 
-<p align="center">
-  <img src="https://cdn.activitysmith.com/features/progress-live-activity.png" alt="Progress Live Activity stream example" width="680" />
-</p>
+![Progress Live Activity stream example](https://cdn.activitysmith.com/features/progress-live-activity.png)
 
 ```ts
 await activitysmith.liveActivities.stream("search-reindex", {
@@ -229,9 +203,7 @@ await activitysmith.liveActivities.stream("search-reindex", {
 
 #### Alert
 
-<p align="center">
-  <img src="https://cdn.activitysmith.com/features/alert-live-activity.png" alt="Alert Live Activity stream example" width="680" />
-</p>
+![Alert Live Activity stream example](https://cdn.activitysmith.com/features/alert-live-activity.png)
 
 ```ts
 await activitysmith.liveActivities.stream("customer-ops", {
@@ -247,9 +219,7 @@ await activitysmith.liveActivities.stream("customer-ops", {
 
 #### Timer
 
-<p align="center">
-  <img src="https://cdn.activitysmith.com/features/timer-live-activity.png" alt="Timer Live Activity showing a benchmark run countdown" width="680" />
-</p>
+![Timer Live Activity stream example](https://cdn.activitysmith.com/features/timer-live-activity.png)
 
 ```ts
 await activitysmith.liveActivities.stream("benchmark-run", {
@@ -269,7 +239,7 @@ To start at 00:00 and count up, set `counts_down: false` and leave out `duration
 
 ### End Live Activity
 
-Call `endStream(...)` with the same `streamKey` 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.
+Call `endStream(...)` with the same `streamKey` to dismiss the Live Activity. You can include final values before it is removed. Set `auto_dismiss_seconds` to dismiss it after a delay in seconds, or `auto_dismiss_minutes` for minutes. Use `0` for immediate dismissal. Seconds take precedence if both are set.
 
 ```ts
 await activitysmith.liveActivities.endStream("prod-web-1", {
@@ -281,23 +251,76 @@ await activitysmith.liveActivities.endStream("prod-web-1", {
       { label: "CPU", value: 7, unit: "%" },
       { label: "MEM", value: 38, unit: "%" },
     ],
-    auto_dismiss_minutes: 2,
+    auto_dismiss_seconds: 30,
   },
 });
 ```
 
+### Icons and Badges
+
+Add more context to Live Activities with icons and badges.
+
+#### Icon
+
+Supported Live Activity types: `stats`, `metrics`, `progress`, `segmented_progress`, `alert`, and `timer`.
+
+![Metrics Live Activity with an SF Symbol icon on the iPhone Lock Screen](https://cdn.activitysmith.com/features/metrics-live-activity-with-icon.png)
+
+```ts
+await activitysmith.liveActivities.stream("prod-web-1", {
+  content_state: ActivitySmith.contentState({
+    title: "Server Health",
+    subtitle: "prod-web-1",
+    type: "metrics",
+    icon: ActivitySmith.alertIcon("server.rack", { color: "blue" }),
+    metrics: [
+      { label: "CPU", value: 18, unit: "%" },
+      { 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.
+
+![Progress Live Activity with a badge on the iPhone Lock Screen](https://cdn.activitysmith.com/features/progress-live-activity-with-badge.png)
+
+```ts
+await activitysmith.liveActivities.stream("nightly-database-backup", {
+  content_state: ActivitySmith.contentState({
+    title: "Nightly Database Backup",
+    subtitle: "verify restore",
+    type: "progress",
+    badge: ActivitySmith.alertBadge("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`
+
 ### Live Activity Action
 
+![Metrics Live Activity with action](https://cdn.activitysmith.com/features/metrics-live-activity-action.png)
+
 Live Activities can include an action button.
 
-- `open_url`: open an HTTPS URL.
-- `open_url` with a `shortcuts://` URL: run an Apple Shortcut, for example to open an app.
+- `open_url`: open an HTTP or HTTPS URL.
+- `open_url` with a `shortcuts://run-shortcut?name=...` URL: run a specific iPhone Shortcut, for example to open an app.
 - `webhook`: trigger a backend GET/POST workflow.
 
-<p align="center">
-  <img src="https://cdn.activitysmith.com/features/metrics-live-activity-action.png" alt="Live Activity with action button" width="680" />
-</p>
-
 #### Open URL action
 
 ```ts
@@ -314,7 +337,7 @@ await activitysmith.liveActivities.stream("prod-web-1", {
   action: {
     title: "Dashboard",
     type: "open_url",
-    url: "https://ops.example.com/servers/prod-web-1",
+    url: "https://status.example.com/servers/prod-web-1",
   },
 });
 ```
@@ -322,13 +345,15 @@ await activitysmith.liveActivities.stream("prod-web-1", {
 #### Apple Shortcut action
 
 ```ts
-await activitysmith.liveActivities.stream("deploy-payments-api", {
+await activitysmith.liveActivities.stream("prod-web-1", {
   content_state: {
-    title: "Deploying payments-api",
-    subtitle: "Running database migrations",
-    type: "segmented_progress",
-    number_of_steps: 5,
-    current_step: 3,
+    title: "Server Health",
+    subtitle: "prod-web-1",
+    type: "metrics",
+    metrics: [
+      { label: "CPU", value: 76, unit: "%" },
+      { label: "MEM", value: 52, unit: "%" },
+    ],
   },
   action: {
     title: "Chat with Jarvis",
@@ -364,9 +389,7 @@ await activitysmith.liveActivities.stream("search-reindex", {
 
 #### Secondary action
 
-<p align="center">
-  <img src="https://cdn.activitysmith.com/features/live-activity-secondary-action.png" alt="Alert Live Activity with primary and secondary action buttons" width="680" />
-</p>
+![Alert Live Activity with primary and secondary action buttons](https://cdn.activitysmith.com/features/live-activity-secondary-action.png)
 
 Use `secondary_action` when you want a second button beside the primary `action`.
 
@@ -411,76 +434,13 @@ await activitysmith.liveActivities.stream("agent-approval", {
 });
 ```
 
-### Icons and Badges
+## Lock Screen Widgets
 
-Add more context to Live Activities with icons and badges.
+![Lock screen widgets](https://cdn.activitysmith.com/features/lock-screen-widgets.png)
 
-#### Icon
+ActivitySmith lets you display any value on your Lock Screen with widgets - SaaS metrics, revenue, signups, uptime, habits, or anything else you want to track. Create a metric in the [web app](https://activitysmith.com/app/widgets), then update the metric value using our API, add a widget to your lock screen and it will fetch the latest update automatically.
 
-Supported Live Activity types: `stats`, `metrics`, `progress`, `segmented_progress`, `alert`, and `timer`.
-
-<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>
-
-```ts
-await activitysmith.liveActivities.stream("prod-web-1", {
-  content_state: ActivitySmith.contentState({
-    title: "Server Health",
-    subtitle: "prod-web-1",
-    type: "metrics",
-    icon: ActivitySmith.alertIcon("server.rack", { color: "blue" }),
-    metrics: [
-      { label: "CPU", value: 18, unit: "%" },
-      { 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>
-
-```ts
-await activitysmith.liveActivities.stream("nightly-database-backup", {
-  content_state: ActivitySmith.contentState({
-    title: "Nightly Database Backup",
-    subtitle: "verify restore",
-    type: "progress",
-    badge: ActivitySmith.alertBadge("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`
-
-## Widgets
-
-<p align="center">
-  <img src="https://cdn.activitysmith.com/features/lock-screen-widgets.png" alt="Lock screen widgets" width="680" />
-</p>
-
-ActivitySmith lets you display any value on your Lock Screen with widgets - SaaS metrics, revenue, signups, uptime, habits, or anything else you want to track. Create a metric in the <a href="https://activitysmith.com/app/widgets" target="_blank" rel="noopener noreferrer">web app</a>, then update the metric value using our API, add a widget to your lock screen and it will fetch the latest update automatically.
-
-<p align="center">
-  <img src="https://cdn.activitysmith.com/features/create-widget-metric.png" alt="Create widget metric" width="680" />
-</p>
+![Create widget metric](https://cdn.activitysmith.com/features/create-widget-metric.png)
 
 Use the metric key to update its value.
 
@@ -496,92 +456,112 @@ await activitysmith.metrics.update("prod.status", "healthy");
 
 ## App Icon Badge Count
 
-<p align="center">
-  <img src="https://cdn.activitysmith.com/features/badge-count.png" alt="ActivitySmith app icon with an App Icon Badge Count" width="680" />
-</p>
+![ActivitySmith app icon with an App Icon Badge Count](https://cdn.activitysmith.com/features/badge-count.png)
 
 Show the number you care about on your ActivitySmith app icon. Track MRR, a customer count, a stock price, or any other value you want to keep in view.
 
-Set or update the badge value.
+### Set or update the badge value
 
-```ts
+```js
 await activitysmith.badgeCount(8333);
 ```
 
-To clear the badge, set its value to 0.
+### Clear the badge
 
-```ts
+Pass `0` to clear the badge.
+
+```js
 await activitysmith.badgeCount(0);
 ```
 
-## Channels
-
-Use `channels` to target specific team members or devices
+## Tags
 
-### Push Notifications
+Use `tags` to organize and filter your Push Notification and Live Activity history. Tags are created automatically when you first use them.
 
-```ts
+```js
 await activitysmith.notifications.send({
   title: "New subscription 💸",
   message: "Customer upgraded to Pro plan",
-  channels: ["sales", "customer-success"],
+  tags: ["user:382", "billing"],
 });
 ```
 
-### Live Activities
+On Live Activity stream updates and legacy `update` or `end` calls, omit `tags` to keep existing Tags, supply a list to replace them, or pass `tags: []` to clear them.
 
-```ts
-await activitysmith.liveActivities.start({
-  content_state: {
-    title: "Nightly Database Backup",
-    subtitle: "verify restore",
-    type: "progress",
-    percentage: 62,
-  },
-  channels: ["sales", "customer-success"],
+```js
+await activitysmith.liveActivities.update({
+  activity_id: "YOUR_ACTIVITY_ID",
+  content_state: { title: "Customer Import", percentage: 60 },
+  tags: [],
 });
 ```
 
-### App Icon Badge Count
+`endStream` also accepts final Tags and Metadata. Omit them to preserve existing values, or supply empty collections to clear them.
 
-```ts
-await activitysmith.badgeCount(3, {
-  channels: ["sales", "customer-success"],
+## Metadata
+
+Metadata adds information to Push Notification and Live Activity details in ActivitySmith. It does not appear in the notification or Live Activity on your device.
+
+```js
+await activitysmith.notifications.send({
+  title: "New subscription 💸",
+  metadata: { customer_id: "382", plan: "Pro", amount: 29, trial: false },
+});
+
+await activitysmith.liveActivities.stream("customer-import", {
+  content_state: { title: "Customer Import", type: "progress", percentage: 60 },
+  metadata: { job_id: "import-382", records: 1200 },
 });
 ```
 
-## Tags
+Supported on Push Notifications, Live Activity streams (including stream ending), and legacy `start`, `update`, and `end` calls. On updates or end calls, omit `metadata` to keep it, supply an object to replace it, or send `{}` to clear it.
 
-Use `tags` to organize and filter your Push Notification and Live Activity history. Tags are created automatically when you first use them.
+Values can be strings, numbers, or booleans. Metadata supports up to 50 entries and 16 KB of JSON, with keys up to 100 characters and strings up to 4,000 characters. Nested objects, arrays, and null values are not supported.
 
-```ts
+## Channels
+
+Use `channels` to target specific team members or devices when sending Push Notifications, Live Activities, or App Icon Badge Count updates. Omit it for account-wide delivery.
+
+```js
 await activitysmith.notifications.send({
   title: "New subscription 💸",
   message: "Customer upgraded to Pro plan",
-  tags: ["user:382", "billing"],
+  channels: ["sales", "customer-success"],
+});
+
+await activitysmith.liveActivities.stream("nightly-backup", {
+  content_state: {
+    title: "Nightly database backup",
+    number_of_steps: 3,
+    current_step: 1,
+    type: "segmented_progress",
+  },
+  channels: ["ios-builds"],
+});
+
+await activitysmith.badgeCount(3, {
+  channels: ["sales", "customer-success"],
 });
 ```
 
 ## Error Handling
 
-```ts
+SDK calls return promises, so you can wrap API calls with `try/catch`:
+
+```js
 try {
-  await activitysmith.notifications.send({
-    title: "New subscription 💸",
-  });
+  await activitysmith.notifications.send({ title: "Hello" });
 } catch (error) {
   console.error(error);
 }
 ```
 
-## TypeScript Support
-
-This package is written in TypeScript and ships with type definitions out of the box.
+## Additional Resources
 
-## Requirements
+### [NPM Package](https://www.npmjs.com/package/activitysmith)
 
-- Node.js 18 or newer
+Install the ActivitySmith Node.js SDK from npm
 
-## License
+### [Source Code](https://github.com/ActivitySmithHQ/activitysmith-node)
 
-MIT
+View the Node.js SDK source on GitHub
diff --git a/src/ActivitySmith.ts b/src/ActivitySmith.ts
index d262b48..1fbc929 100644
--- a/src/ActivitySmith.ts
+++ b/src/ActivitySmith.ts
@@ -8,10 +8,15 @@ import {
 
 const SDK_VERSION = "1.10.0";
 const SDK_HEADER_NAME = "X-ActivitySmith-SDK";
-const SDK_HEADER_VALUE = `node-v${SDK_VERSION}`;
+const DEFAULT_SDK_NAME = "node";
+const SDK_HEADER_VALUE = `${DEFAULT_SDK_NAME}-v${SDK_VERSION}`;
 
 export interface ActivitySmithOptions {
   apiKey: string;
+  sdk?: {
+    name: string;
+    version: string;
+  };
 }
 
 type PushRequestBody = Parameters<PushNotificationsApi["sendPushNotification"]>[0]["pushNotificationRequest"];
@@ -123,6 +128,24 @@ function compactObject<T extends Record<string, unknown>>(value: T): T {
   ) as T;
 }
 
+function sdkHeaderValue(sdk: ActivitySmithOptions["sdk"]): string {
+  if (!sdk) {
+    return SDK_HEADER_VALUE;
+  }
+
+  const name = sdk.name.trim().toLowerCase();
+  const version = sdk.version.trim();
+
+  if (!/^[a-z][a-z0-9]*$/.test(name)) {
+    throw new Error("ActivitySmith: sdk.name must start with a letter and contain only letters and numbers");
+  }
+  if (!version) {
+    throw new Error("ActivitySmith: sdk.version is required");
+  }
+
+  return `${name}-v${version}`;
+}
+
 function contentState(value: LiveActivityContentState): LiveActivityContentState {
   return compactObject(value);
 }
@@ -379,7 +402,7 @@ export class ActivitySmith {
     const config = new Configuration({
       accessToken: opts.apiKey,
       headers: {
-        [SDK_HEADER_NAME]: SDK_HEADER_VALUE,
+        [SDK_HEADER_NAME]: sdkHeaderValue(opts.sdk),
       },
     });
 
diff --git a/tests/resources.test.js b/tests/resources.test.js
index 4899022..695d107 100644
--- a/tests/resources.test.js
+++ b/tests/resources.test.js
@@ -806,3 +806,73 @@ describe("resource wrappers", () => {
     expect(updateSpy).toHaveBeenCalledWith(request, undefined);
   });
 });
+
+
+describe("legacy Tags serialization", () => {
+  afterEach(() => vi.unstubAllGlobals());
+  for (const method of ["update", "end"]) {
+    for (const tags of [undefined, ["billing"], []]) {
+      it(`${method} serializes Tags ${JSON.stringify(tags)}`, async () => {
+        const ActivitySmith = require("../dist/src/index.js");
+        let body;
+        vi.stubGlobal("fetch", async (_url, init) => {
+          body = JSON.parse(init.body);
+          return new Response(JSON.stringify({success: true}), {status: 200, headers: {"Content-Type": "application/json"}});
+        });
+        const client = new ActivitySmith({ apiKey: "test" });
+        await client.liveActivities[method]({activity_id: "activity-1", content_state: {title: "Job"}, tags});
+        expect(Object.hasOwn(body, "tags")).toBe(tags !== undefined);
+        expect(body.tags).toEqual(tags);
+      });
+    }
+  }
+});
+
+
+describe("Metadata serialization", () => {
+  afterEach(() => vi.unstubAllGlobals());
+  for (const method of ["send", "start", "update", "end", "stream", "endStream"]) {
+    for (const metadata of [undefined, {}, { order: "382", ready: false, count: 0, empty: "", ratio: 1.25 }]) {
+      it(`${method} preserves Metadata ${JSON.stringify(metadata)}`, async () => {
+        const ActivitySmith = require("../dist/src/index.js");
+        let body;
+        vi.stubGlobal("fetch", async (_url, init) => {
+          body = JSON.parse(init.body);
+          return new Response(JSON.stringify({success: true}), {status: 200, headers: {"Content-Type": "application/json"}});
+        });
+        const client = new ActivitySmith({apiKey: "test"});
+        if (method === "send") await client.notifications.send({title: "Job", metadata});
+        else {
+          const request = {activity_id: "activity-1", content_state: {title: "Job"}, metadata};
+          if (method === "stream" || method === "endStream") await client.liveActivities[method]("job", request);
+          else await client.liveActivities[method](request);
+        }
+        expect(Object.hasOwn(body, "metadata")).toBe(metadata !== undefined);
+        expect(body.metadata).toEqual(metadata);
+        expect(body.content_state?.metadata).toBeUndefined();
+      });
+    }
+  }
+});
+
+
+describe("External URLs and final stream fields", () => {
+  afterEach(() => vi.unstubAllGlobals());
+  it("preserves custom destinations and explicit empty final history fields", async () => {
+    const ActivitySmith = require("../dist/src/index.js");
+    let body;
+    vi.stubGlobal("fetch", async (_url, init) => {
+      body = JSON.parse(init.body);
+      return new Response(JSON.stringify({success:true}), {status:200, headers:{"Content-Type":"application/json"}});
+    });
+    const client = new ActivitySmith({apiKey:"test"});
+    for (const url of ["http://example.com", "https://example.com", "shortcuts://run-shortcut?name=Test", "spotify://", "spotify:track:123"]) {
+      await client.notifications.send({title:"Job",redirection:url,actions:[{title:"Open",type:"open_url",url}]});
+      expect(body.redirection).toBe(url); expect(body.actions[0].url).toBe(url);
+    }
+    for (const tags of [undefined, [], ["finished"]]) {
+      await client.liveActivities.endStream("job", {tags, metadata:{}});
+      expect(body.tags).toEqual(tags); expect(body.metadata).toEqual({});
+    }
+  });
+});
diff --git a/tests/smoke.test.js b/tests/smoke.test.js
index 354ef97..499803e 100644
--- a/tests/smoke.test.js
+++ b/tests/smoke.test.js
@@ -4,6 +4,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 const require = createRequire(import.meta.url);
 const packageJson = require("../package.json");
 const expectedSdkHeader = `node-v${packageJson.version}`;
+const expectedCliSdkHeader = `cli-v${packageJson.version}`;
 
 describe("smoke", () => {
   const originalFetch = globalThis.fetch;
@@ -69,4 +70,34 @@ describe("smoke", () => {
       expect(call[1]?.headers?.["X-ActivitySmith-SDK"]).toBe(expectedSdkHeader);
     }
   });
+
+  it("allows official wrappers to override the SDK tracking identity", async () => {
+    const fetchSpy = vi.fn(async () =>
+      new Response(
+        JSON.stringify({
+          success: true,
+          devices_notified: 1,
+        }),
+        {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        },
+      ),
+    );
+
+    globalThis.fetch = fetchSpy;
+
+    const ActivitySmith = require("../dist/src/index.js");
+    const client = new ActivitySmith({
+      apiKey: "test",
+      sdk: { name: "cli", version: packageJson.version },
+    });
+
+    await client.notifications.send({ title: "Build Failed" });
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    expect(fetchSpy.mock.calls[0][1]?.headers?.["X-ActivitySmith-SDK"]).toBe(
+      expectedCliSdkHeader,
+    );
+  });
 });

From f2a17c880571db87945d71868babd537b36b221e Mon Sep 17 00:00:00 2001
From: bardonadam <adam@initsignal.com>
Date: Tue, 15 Sep 2026 20:12:43 +0700
Subject: [PATCH 03/12] fix: remove internal operations from the generated
 client

Use the generated output from canonical backend 49ad7b083b50f53bc3d81edb77ca6597845160a2. Health checks and app changelog are first-party operations, not part of the developer API. Preserve the existing wrapper and README preparation.

Verification: SDK tests passed; generated source scanned for removed operations/models; provenance matches the deployed public contract.

Initiated-by: user

Implemented-by: codex
---
 generated/apis/PublicApi.ts   |  96 -----------------
 generated/apis/index.ts       |   1 -
 generated/models/index.ts     | 187 ----------------------------------
 generated/openapi-source.json |   4 +-
 4 files changed, 2 insertions(+), 286 deletions(-)
 delete mode 100644 generated/apis/PublicApi.ts

diff --git a/generated/apis/PublicApi.ts b/generated/apis/PublicApi.ts
deleted file mode 100644
index 32cbc37..0000000
--- a/generated/apis/PublicApi.ts
+++ /dev/null
@@ -1,96 +0,0 @@
-/* tslint:disable */
-/* eslint-disable */
-/**
- * ActivitySmith API
- * Send push notifications and Live Activities to your own devices via a single API key.
- *
- * The version of the OpenAPI document: 1.0.0
- * 
- *
- * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
- * https://openapi-generator.tech
- * Do not edit the class manually.
- */
-
-
-import * as runtime from '../runtime';
-import type {
-  ChangelogListResponse,
-  HealthResponse,
-} from '../models/index';
-
-export interface ListPublicChangelogEntriesRequest {
-    platform?: string;
-    limit?: number;
-}
-
-/**
- * 
- */
-export class PublicApi extends runtime.BaseAPI {
-
-    /**
-     * Returns the current availability of the ActivitySmith API and its required services. No authentication is required.
-     * Get API Health
-     */
-    async getApiHealthRaw(initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<HealthResponse>> {
-        const queryParameters: any = {};
-
-        const headerParameters: runtime.HTTPHeaders = {};
-
-        const response = await this.request({
-            path: `/health`,
-            method: 'GET',
-            headers: headerParameters,
-            query: queryParameters,
-        }, initOverrides);
-
-        return new runtime.JSONApiResponse(response);
-    }
-
-    /**
-     * Returns the current availability of the ActivitySmith API and its required services. No authentication is required.
-     * Get API Health
-     */
-    async getApiHealth(initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<HealthResponse> {
-        const response = await this.getApiHealthRaw(initOverrides);
-        return await response.value();
-    }
-
-    /**
-     * Returns published ActivitySmith app changelog entries. No authentication is required.
-     * List Public Changelog Entries
-     */
-    async listPublicChangelogEntriesRaw(requestParameters: ListPublicChangelogEntriesRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ChangelogListResponse>> {
-        const queryParameters: any = {};
-
-        if (requestParameters['platform'] != null) {
-            queryParameters['platform'] = requestParameters['platform'];
-        }
-
-        if (requestParameters['limit'] != null) {
-            queryParameters['limit'] = requestParameters['limit'];
-        }
-
-        const headerParameters: runtime.HTTPHeaders = {};
-
-        const response = await this.request({
-            path: `/changelog`,
-            method: 'GET',
-            headers: headerParameters,
-            query: queryParameters,
-        }, initOverrides);
-
-        return new runtime.JSONApiResponse(response);
-    }
-
-    /**
-     * Returns published ActivitySmith app changelog entries. No authentication is required.
-     * List Public Changelog Entries
-     */
-    async listPublicChangelogEntries(requestParameters: ListPublicChangelogEntriesRequest = {}, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ChangelogListResponse> {
-        const response = await this.listPublicChangelogEntriesRaw(requestParameters, initOverrides);
-        return await response.value();
-    }
-
-}
diff --git a/generated/apis/index.ts b/generated/apis/index.ts
index b74c2df..ecb06b5 100644
--- a/generated/apis/index.ts
+++ b/generated/apis/index.ts
@@ -3,5 +3,4 @@
 export * from './AppIconBadgesApi';
 export * from './LiveActivitiesApi';
 export * from './MetricsApi';
-export * from './PublicApi';
 export * from './PushNotificationsApi';
diff --git a/generated/models/index.ts b/generated/models/index.ts
index eb6b708..035a9f2 100644
--- a/generated/models/index.ts
+++ b/generated/models/index.ts
@@ -243,117 +243,6 @@ export interface BadRequestError {
      */
     message: string;
 }
-/**
- * 
- * @export
- * @interface ChangelogEntry
- */
-export interface ChangelogEntry {
-    /**
-     * 
-     * @type {string}
-     * @memberof ChangelogEntry
-     */
-    id: string;
-    /**
-     * 
-     * @type {string}
-     * @memberof ChangelogEntry
-     */
-    platform: string;
-    /**
-     * 
-     * @type {string}
-     * @memberof ChangelogEntry
-     */
-    version: string;
-    /**
-     * 
-     * @type {string}
-     * @memberof ChangelogEntry
-     */
-    title: string;
-    /**
-     * 
-     * @type {string}
-     * @memberof ChangelogEntry
-     */
-    subtitle: string | null;
-    /**
-     * 
-     * @type {string}
-     * @memberof ChangelogEntry
-     */
-    hero_image_url: string | null;
-    /**
-     * 
-     * @type {string}
-     * @memberof ChangelogEntry
-     */
-    cta_title: string;
-    /**
-     * 
-     * @type {string}
-     * @memberof ChangelogEntry
-     */
-    published_at: string | null;
-    /**
-     * 
-     * @type {Array<ChangelogItem>}
-     * @memberof ChangelogEntry
-     */
-    items: Array<ChangelogItem>;
-}
-/**
- * 
- * @export
- * @interface ChangelogItem
- */
-export interface ChangelogItem {
-    /**
-     * 
-     * @type {string}
-     * @memberof ChangelogItem
-     */
-    icon?: string | null;
-    /**
-     * 
-     * @type {string}
-     * @memberof ChangelogItem
-     */
-    title: string;
-    /**
-     * 
-     * @type {string}
-     * @memberof ChangelogItem
-     */
-    body: string;
-    /**
-     * 
-     * @type {string}
-     * @memberof ChangelogItem
-     */
-    image_url?: string | null;
-    /**
-     * 
-     * @type {string}
-     * @memberof ChangelogItem
-     */
-    accent_color?: string | null;
-}
-/**
- * 
- * @export
- * @interface ChangelogListResponse
- */
-export interface ChangelogListResponse {
-    /**
-     * 
-     * @type {Array<ChangelogEntry>}
-     * @memberof ChangelogListResponse
-     */
-    changelogs: Array<ChangelogEntry>;
-}
 /**
  * 
  * @export
@@ -935,82 +824,6 @@ export interface ForbiddenError {
      */
     message: string;
 }
-/**
- * 
- * @export
- * @interface HealthCheck
- */
-export interface HealthCheck {
-    /**
-     * 
-     * @type {string}
-     * @memberof HealthCheck
-     */
-    name: HealthCheckNameEnum;
-    /**
-     * 
-     * @type {string}
-     * @memberof HealthCheck
-     */
-    status: HealthCheckStatusEnum;
-    /**
-     * 
-     * @type {number}
-     * @memberof HealthCheck
-     */
-    duration_ms: number;
-}
-
-
-/**
- * @export
- */
-export const HealthCheckNameEnum = {
-    Database: 'database',
-    Redis: 'redis'
-} as const;
-export type HealthCheckNameEnum = typeof HealthCheckNameEnum[keyof typeof HealthCheckNameEnum];
-
-/**
- * @export
- */
-export const HealthCheckStatusEnum = {
-    Ok: 'ok',
-    Failed: 'failed'
-} as const;
-export type HealthCheckStatusEnum = typeof HealthCheckStatusEnum[keyof typeof HealthCheckStatusEnum];
-
-/**
- * 
- * @export
- * @interface HealthResponse
- */
-export interface HealthResponse {
-    /**
-     * 
-     * @type {boolean}
-     * @memberof HealthResponse
-     */
-    ok: boolean;
-    /**
-     * 
-     * @type {string}
-     * @memberof HealthResponse
-     */
-    service: string;
-    /**
-     * 
-     * @type {string}
-     * @memberof HealthResponse
-     */
-    timestamp: string;
-    /**
-     * 
-     * @type {Array<HealthCheck>}
-     * @memberof HealthResponse
-     */
-    checks: Array<HealthCheck>;
-}
 /**
  * Optional action button shown in the Live Activity UI. Use action for the primary button, or secondary_action for a secondary button on alert, progress, and segmented_progress Live Activities.
  * @export
diff --git a/generated/openapi-source.json b/generated/openapi-source.json
index 5a616d3..dc05717 100644
--- a/generated/openapi-source.json
+++ b/generated/openapi-source.json
@@ -1,6 +1,6 @@
 {
   "repository": "ActivitySmithHQ/activitysmith-backend",
-  "commit": "3cd1df5f1296777bacfad731eac9f91d27d01c6e",
+  "commit": "49ad7b083b50f53bc3d81edb77ca6597845160a2",
   "path": "openapi.json",
-  "sha256": "e112ddb9a069dc0ad87a123d0be1286ff0a671da505fabfdf4bb94ff6bcb444f"
+  "sha256": "b7e33cd485df8ddc5d7fb7b57b61106fd6f8ff3ffa7cc7bef4ac1ccbbb0cede7"
 }

From 5897b29546bfe6d58d09503fa34b2d0a46eaf973 Mon Sep 17 00:00:00 2001
From: bardonadam <adam@initsignal.com>
Date: Tue, 15 Sep 2026 20:14:31 +0700
Subject: [PATCH 04/12] fix: clear stale generated artifacts before packaging

TypeScript clean can leave JavaScript from deleted source files in dist. Remove the output directory as well so retired internal APIs cannot leak into npm packages.

Verification: reproduced stale PublicApi.js after regeneration; clean build now removes it; 55 tests and local npm pack passed.

Initiated-by: user

Implemented-by: codex
---
 package.json                 |  2 +-
 tests/public-surface.test.js | 11 +++++++++++
 2 files changed, 12 insertions(+), 1 deletion(-)
 create mode 100644 tests/public-surface.test.js

diff --git a/package.json b/package.json
index c69c536..53fb755 100644
--- a/package.json
+++ b/package.json
@@ -44,7 +44,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "clean": "tsc -b --clean",
+    "clean": "tsc -b --clean && node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "build": "npm run clean && tsc -b",
     "prepublishOnly": "npm run build",
     "test": "npm run build && vitest run"
diff --git a/tests/public-surface.test.js b/tests/public-surface.test.js
new file mode 100644
index 0000000..e713288
--- /dev/null
+++ b/tests/public-surface.test.js
@@ -0,0 +1,11 @@
+import { readdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { expect, it } from "vitest";
+
+const require = createRequire(import.meta.url);
+it("does not package removed internal APIs or models", () => {
+  const generated = require("../dist/generated/index.js");
+  expect(generated).not.toHaveProperty("PublicApi");
+  const files = readdirSync(new URL("../dist/", import.meta.url), { recursive: true });
+  expect(files.filter(file => /(?:PublicApi|HealthResponse|HealthCheck|ChangelogEntry|ChangelogItem|ChangelogListResponse)\.(?:js|d\.ts)$/.test(file))).toEqual([]);
+});

From e50d034dfa9213b1d752f3d0d43776e0f95ba02e Mon Sep 17 00:00:00 2001
From: bardonadam <adam@initsignal.com>
Date: Tue, 15 Sep 2026 20:42:41 +0700
Subject: [PATCH 05/12] docs: align README link examples with SDK documentation

Repeat supported destinations within each relevant section, use iOS Shortcut terminology, and remove app-version notes. Live Activity action support remains unchanged.

Verification: README sync check passed; code fences unchanged; Markdown links and whitespace checked.

Initiated-by: user
Implemented-by: codex
---
 README.md | 32 +++++++++++++++++++++++++++-----
 1 file changed, 27 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 6099457..70a785d 100644
--- a/README.md
+++ b/README.md
@@ -65,7 +65,15 @@ What will work:
 
 ### Push Notifications with Redirection
 
-Open a web page, an iPhone Shortcut, or an installed app when someone taps the notification. Set `redirection` to an HTTP, HTTPS, or Shortcuts URL, or an app deep link such as `spotify:track:123`.
+Open a web page, run an iOS Shortcut, or open an app when someone taps the notification. `redirection` supports:
+
+- **HTTP/HTTPS:** Web pages, e.g. `https://example.com`
+- **Shortcuts:** Run Jarvis with `shortcuts://run-shortcut?name=Jarvis` <!-- full-width -->
+- **App deep links:** Installed apps or specific content within them
+  - **Spotify:** A track, e.g. `spotify:track:6rqhFgbbKwnb9MLmUQDhG6`
+  - **Termius:** `termius://` to open the app
+  - **Claude:** `claude://code` to open the Code tab
+  - **ChatGPT:** `chatgpt://` to open the app <!-- Verify ChatGPT URL scheme on iOS before publishing -->
 
 ```js
 await activitysmith.notifications.send({
@@ -79,7 +87,17 @@ await activitysmith.notifications.send({
 
 ![Actionable Push Notification with redirection and actions](https://cdn.activitysmith.com/features/actionable-push-notifications-2.png)
 
-For expanded notification actions, `open_url` supports HTTP, HTTPS, Shortcuts, and installed app deep links. Webhooks are executed by the ActivitySmith backend and must use HTTPS. Custom app links require iOS 1.13.4 build 2 or later and an installed app that handles the URL.
+`open_url` actions open a web page, run an iOS Shortcut, or open an app when someone taps the button. Supported links:
+
+- **HTTP/HTTPS:** Web pages, e.g. `https://example.com`
+- **Shortcuts:** Run Jarvis with `shortcuts://run-shortcut?name=Jarvis` <!-- full-width -->
+- **App deep links:** Installed apps or specific content within them
+  - **Spotify:** A track, e.g. `spotify:track:6rqhFgbbKwnb9MLmUQDhG6`
+  - **Termius:** `termius://` to open the app
+  - **Claude:** `claude://code` to open the Code tab
+  - **ChatGPT:** `chatgpt://` to open the app <!-- Verify ChatGPT URL scheme on iOS before publishing -->
+
+Webhooks are executed by the ActivitySmith backend and must use HTTPS.
 
 ```js
 await activitysmith.notifications.send({
@@ -317,12 +335,16 @@ Choose from these colors for the Live Activity accent, including progress bars a
 
 Live Activities can include an action button.
 
-- `open_url`: open an HTTP or HTTPS URL.
-- `open_url` with a `shortcuts://run-shortcut?name=...` URL: run a specific iPhone Shortcut, for example to open an app.
-- `webhook`: trigger a backend GET/POST workflow.
+- `open_url`: Open a web page or run an iOS Shortcut
+- `webhook`: Trigger a backend GET/POST workflow
 
 #### Open URL action
 
+Open a web page or run an iOS Shortcut when someone taps the button. Supported links:
+
+- **HTTP/HTTPS:** Web pages, e.g. `https://example.com`
+- **Shortcuts:** Run Jarvis with `shortcuts://run-shortcut?name=Jarvis` <!-- full-width -->
+
 ```ts
 await activitysmith.liveActivities.stream("prod-web-1", {
   content_state: {

From fe7a699926a394efbb12d9e6b625f9d529768ab5 Mon Sep 17 00:00:00 2001
From: bardonadam <adam@initsignal.com>
Date: Tue, 15 Sep 2026 20:47:58 +0700
Subject: [PATCH 06/12] docs: omit redundant repository resources from SDK
 READMEs

Keep Source Code resources in website docs only. Preserve package links and omit the empty Go resource section.

Verification: README converter test and six-repository sync check passed; scoped diffs checked.

Initiated-by: user
Implemented-by: codex
---
 README.md | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/README.md b/README.md
index 70a785d..045a928 100644
--- a/README.md
+++ b/README.md
@@ -583,7 +583,3 @@ try {
 ### [NPM Package](https://www.npmjs.com/package/activitysmith)
 
 Install the ActivitySmith Node.js SDK from npm
-
-### [Source Code](https://github.com/ActivitySmithHQ/activitysmith-node)
-
-View the Node.js SDK source on GitHub

From 58a2850572adbd78ec6fb78001cb540e2c9574f7 Mon Sep 17 00:00:00 2001
From: bardonadam <adam@initsignal.com>
Date: Tue, 15 Sep 2026 20:56:10 +0700
Subject: [PATCH 07/12] docs: render Live Activity previews without list
 bullets

Use standalone preview images and captions in SDK READMEs; retain the website grid source.

Verification: converter test and six-repository sync check passed; all preview images and code fences preserved.

Initiated-by: user
Implemented-by: codex
---
 README.md | 24 ++++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 045a928..da1f62e 100644
--- a/README.md
+++ b/README.md
@@ -132,17 +132,29 @@ await activitysmith.notifications.send({
 
 Choose the Live Activity type that matches what you want to show:
 
-- ![Stats Live Activity with six labeled sales metrics](https://cdn.activitysmith.com/features/stats-live-activity.png) **Stats**: Show up to 8 labeled values on your Lock Screen, from revenue and orders to uptime and conversion.
+![Stats Live Activity with six labeled sales metrics](https://cdn.activitysmith.com/features/stats-live-activity.png)
 
-- ![Metrics Live Activity with CPU and memory values](https://cdn.activitysmith.com/features/metrics-live-activity-start.png) **Metrics**: Track two related values with segmented bars, such as CPU and memory.
+**Stats**: Show up to 8 labeled values on your Lock Screen, from revenue and orders to uptime and conversion.
 
-- ![Segmented Progress Live Activity showing a workflow step](https://cdn.activitysmith.com/features/update-live-activity.png) **Segmented Progress**: Show progress through a known set of steps, like build, test, deploy, and verify.
+![Metrics Live Activity with CPU and memory values](https://cdn.activitysmith.com/features/metrics-live-activity-start.png)
 
-- ![Progress Live Activity showing percentage completion](https://cdn.activitysmith.com/features/progress-live-activity.png) **Progress**: Show percentage progress for jobs that move continuously toward completion.
+**Metrics**: Track two related values with segmented bars, such as CPU and memory.
 
-- ![Alert Live Activity showing a customer reactivation update](https://cdn.activitysmith.com/features/alert-live-activity.png) **Alert**: Show status updates with a clear message, badge, and icon. When you add an action button, `color` controls the button tint.
+![Segmented Progress Live Activity showing a workflow step](https://cdn.activitysmith.com/features/update-live-activity.png)
 
-- ![Timer Live Activity showing a benchmark run countdown](https://cdn.activitysmith.com/features/timer-live-activity.png) **Timer**: Count down from a duration, or count up from 00:00 while a job runs.
+**Segmented Progress**: Show progress through a known set of steps, like build, test, deploy, and verify.
+
+![Progress Live Activity showing percentage completion](https://cdn.activitysmith.com/features/progress-live-activity.png)
+
+**Progress**: Show percentage progress for jobs that move continuously toward completion.
+
+![Alert Live Activity showing a customer reactivation update](https://cdn.activitysmith.com/features/alert-live-activity.png)
+
+**Alert**: Show status updates with a clear message, badge, and icon. When you add an action button, `color` controls the button tint.
+
+![Timer Live Activity showing a benchmark run countdown](https://cdn.activitysmith.com/features/timer-live-activity.png)
+
+**Timer**: Count down from a duration, or count up from 00:00 while a job runs.
 
 ### Start & Update Live Activity
 

From 831c7faf351c087809ec22da4eb63fea21153d6c Mon Sep 17 00:00:00 2001
From: bardonadam <adam@initsignal.com>
Date: Tue, 15 Sep 2026 20:58:17 +0700
Subject: [PATCH 08/12] docs: order Metadata before Tags and Channels

Match the SDK documentation feature priority. Section content and code examples are unchanged.

Verification: section contents compared before and after; README sync and whitespace checks passed.

Initiated-by: user
Implemented-by: codex
---
 README.md | 40 ++++++++++++++++++++--------------------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index da1f62e..431ff0d 100644
--- a/README.md
+++ b/README.md
@@ -508,6 +508,26 @@ Pass `0` to clear the badge.
 await activitysmith.badgeCount(0);
 ```
 
+## Metadata
+
+Metadata adds information to Push Notification and Live Activity details in ActivitySmith. It does not appear in the notification or Live Activity on your device.
+
+```js
+await activitysmith.notifications.send({
+  title: "New subscription 💸",
+  metadata: { customer_id: "382", plan: "Pro", amount: 29, trial: false },
+});
+
+await activitysmith.liveActivities.stream("customer-import", {
+  content_state: { title: "Customer Import", type: "progress", percentage: 60 },
+  metadata: { job_id: "import-382", records: 1200 },
+});
+```
+
+Supported on Push Notifications, Live Activity streams (including stream ending), and legacy `start`, `update`, and `end` calls. On updates or end calls, omit `metadata` to keep it, supply an object to replace it, or send `{}` to clear it.
+
+Values can be strings, numbers, or booleans. Metadata supports up to 50 entries and 16 KB of JSON, with keys up to 100 characters and strings up to 4,000 characters. Nested objects, arrays, and null values are not supported.
+
 ## Tags
 
 Use `tags` to organize and filter your Push Notification and Live Activity history. Tags are created automatically when you first use them.
@@ -532,26 +552,6 @@ await activitysmith.liveActivities.update({
 
 `endStream` also accepts final Tags and Metadata. Omit them to preserve existing values, or supply empty collections to clear them.
 
-## Metadata
-
-Metadata adds information to Push Notification and Live Activity details in ActivitySmith. It does not appear in the notification or Live Activity on your device.
-
-```js
-await activitysmith.notifications.send({
-  title: "New subscription 💸",
-  metadata: { customer_id: "382", plan: "Pro", amount: 29, trial: false },
-});
-
-await activitysmith.liveActivities.stream("customer-import", {
-  content_state: { title: "Customer Import", type: "progress", percentage: 60 },
-  metadata: { job_id: "import-382", records: 1200 },
-});
-```
-
-Supported on Push Notifications, Live Activity streams (including stream ending), and legacy `start`, `update`, and `end` calls. On updates or end calls, omit `metadata` to keep it, supply an object to replace it, or send `{}` to clear it.
-
-Values can be strings, numbers, or booleans. Metadata supports up to 50 entries and 16 KB of JSON, with keys up to 100 characters and strings up to 4,000 characters. Nested objects, arrays, and null values are not supported.
-
 ## Channels
 
 Use `channels` to target specific team members or devices when sending Push Notifications, Live Activities, or App Icon Badge Count updates. Omit it for account-wide delivery.

From 85e3ceb9301ff88707005886050f90608dec0c25 Mon Sep 17 00:00:00 2001
From: bardonadam <adam@initsignal.com>
Date: Tue, 15 Sep 2026 21:01:12 +0700
Subject: [PATCH 09/12] docs: simplify Metadata description

Describe metadata as extra information and remove the paragraph about supported operations and replacement behavior, matching the reviewed SDK docs.

Verification: README sync check passed; code examples and other sections unchanged.

Initiated-by: user
Implemented-by: codex
---
 README.md | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 431ff0d..a57dab7 100644
--- a/README.md
+++ b/README.md
@@ -510,7 +510,7 @@ await activitysmith.badgeCount(0);
 
 ## Metadata
 
-Metadata adds information to Push Notification and Live Activity details in ActivitySmith. It does not appear in the notification or Live Activity on your device.
+Metadata adds extra information to Push Notification and Live Activity details in ActivitySmith. It does not appear in the notification or Live Activity on your device.
 
 ```js
 await activitysmith.notifications.send({
@@ -524,8 +524,6 @@ await activitysmith.liveActivities.stream("customer-import", {
 });
 ```
 
-Supported on Push Notifications, Live Activity streams (including stream ending), and legacy `start`, `update`, and `end` calls. On updates or end calls, omit `metadata` to keep it, supply an object to replace it, or send `{}` to clear it.
-
 Values can be strings, numbers, or booleans. Metadata supports up to 50 entries and 16 KB of JSON, with keys up to 100 characters and strings up to 4,000 characters. Nested objects, arrays, and null values are not supported.
 
 ## Tags

From dcacbe614d7f89fb7c23b1c9b873a8b4d113b363 Mon Sep 17 00:00:00 2001
From: bardonadam <adam@initsignal.com>
Date: Tue, 15 Sep 2026 21:02:20 +0700
Subject: [PATCH 10/12] docs: refine Metadata example and remove redundant
 end-stream note

Include the notification message in Metadata examples and remove the final Tags and Metadata paragraph as requested.

Verification: README sync and whitespace checks passed; inspected changes limited to the requested example and paragraph.

Initiated-by: user
Implemented-by: codex
---
 README.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/README.md b/README.md
index a57dab7..5c37197 100644
--- a/README.md
+++ b/README.md
@@ -515,6 +515,7 @@ Metadata adds extra information to Push Notification and Live Activity details i
 ```js
 await activitysmith.notifications.send({
   title: "New subscription 💸",
+  message: "Customer upgraded to Pro plan",
   metadata: { customer_id: "382", plan: "Pro", amount: 29, trial: false },
 });
 
@@ -548,8 +549,6 @@ await activitysmith.liveActivities.update({
 });
 ```
 
-`endStream` also accepts final Tags and Metadata. Omit them to preserve existing values, or supply empty collections to clear them.
-
 ## Channels
 
 Use `channels` to target specific team members or devices when sending Push Notifications, Live Activities, or App Icon Badge Count updates. Omit it for account-wide delivery.

From d09c1243f64502851ba68ed04fc9015693667e64 Mon Sep 17 00:00:00 2001
From: bardonadam <adam@initsignal.com>
Date: Tue, 15 Sep 2026 21:03:50 +0700
Subject: [PATCH 11/12] docs: format Metadata examples across multiple lines

Expand metadata and content-state objects to one field per line for readability.

Verification: sync check passed; example tokens and CLI JSON values preserved; Python example syntax checked.

Initiated-by: user
Implemented-by: codex
---
 README.md | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 5c37197..560ad77 100644
--- a/README.md
+++ b/README.md
@@ -516,12 +516,24 @@ Metadata adds extra information to Push Notification and Live Activity details i
 await activitysmith.notifications.send({
   title: "New subscription 💸",
   message: "Customer upgraded to Pro plan",
-  metadata: { customer_id: "382", plan: "Pro", amount: 29, trial: false },
+  metadata: {
+    customer_id: "382",
+    plan: "Pro",
+    amount: 29,
+    trial: false,
+  },
 });
 
 await activitysmith.liveActivities.stream("customer-import", {
-  content_state: { title: "Customer Import", type: "progress", percentage: 60 },
-  metadata: { job_id: "import-382", records: 1200 },
+  content_state: {
+    title: "Customer Import",
+    type: "progress",
+    percentage: 60,
+  },
+  metadata: {
+    job_id: "import-382",
+    records: 1200,
+  },
 });
 ```
 

From a68ef387e0744aa8b797a192f8898585d2ab49a1 Mon Sep 17 00:00:00 2001
From: bardonadam <adam@initsignal.com>
Date: Tue, 15 Sep 2026 21:19:11 +0700
Subject: [PATCH 12/12] chore: prepare SDK 1.11.0 feature release

Bump package and SDK identification versions to 1.11.0. Keep the release summary focused on Metadata, Tags, and iOS deep links. Generated package version metadata was regenerated from the unchanged API contract.

Verification: package test suite passed; version metadata and scoped diffs checked. No release tags or package publishing.

Initiated-by: user
Implemented-by: codex
---
 CHANGELOG.md         | 10 ++--------
 package-lock.json    |  4 ++--
 package.json         |  2 +-
 src/ActivitySmith.ts |  2 +-
 4 files changed, 6 insertions(+), 12 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 33d5dc4..d6bf11e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,12 +1,6 @@
-## Unreleased
+## 1.11.0
 
-- Support Push Notification app deep links and final Tags/Metadata when ending a managed Live Activity stream.
-
-- Add Metadata to Push Notifications and Live Activity start, update, end, and stream requests, including empty-object clearing.
-
-- Add Tags replacement and empty-array clearing to legacy Live Activity update and end.
-
-- Add the optional SDK identity override from local commit `8bf44fc` so official wrappers such as the CLI can report their own `X-ActivitySmith-SDK` value. Include this in the next published Node SDK release.
+This version adds support for Metadata and iOS deep links, and expands Tags support when updating or ending Live Activities.
 
 ## 1.10.0
 
diff --git a/package-lock.json b/package-lock.json
index 33d0408..d5b632c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "activitysmith",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "activitysmith",
-      "version": "1.10.0",
+      "version": "1.11.0",
       "license": "MIT",
       "devDependencies": {
         "typescript": "^5.3.3",
diff --git a/package.json b/package.json
index 53fb755..d0b2e27 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "activitysmith",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Official ActivitySmith Node.js SDK",
   "keywords": [
     "activitysmith",
diff --git a/src/ActivitySmith.ts b/src/ActivitySmith.ts
index 1fbc929..ab7a7d0 100644
--- a/src/ActivitySmith.ts
+++ b/src/ActivitySmith.ts
@@ -6,7 +6,7 @@ import {
   PushNotificationsApi,
 } from "../generated/index";
 
-const SDK_VERSION = "1.10.0";
+const SDK_VERSION = "1.11.0";
 const SDK_HEADER_NAME = "X-ActivitySmith-SDK";
 const DEFAULT_SDK_NAME = "node";
 const SDK_HEADER_VALUE = `${DEFAULT_SDK_NAME}-v${SDK_VERSION}`;