@framers/agentos-ext-notifications 0.1.3 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +75 -0
  2. package/manifest.json +1 -1
  3. package/package.json +2 -2
package/README.md ADDED
@@ -0,0 +1,75 @@
1
+ # Notifications
2
+
3
+ This pack gives an agent tools to send, broadcast, and schedule notifications through the pack's `NotificationService`. Delivery uses registered channel callbacks.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @framers/agentos-ext-notifications
9
+ ```
10
+
11
+ Peer dependency: `@framers/agentos` with range `>=0.10.40`.
12
+
13
+ ## Usage
14
+
15
+ ```ts
16
+ import { AgentOS } from '@framers/agentos';
17
+
18
+ const agentos = await AgentOS.create({
19
+ extensionManifest: {
20
+ packs: [{ package: '@framers/agentos-ext-notifications' }],
21
+ },
22
+ });
23
+ ```
24
+
25
+ ## Tools
26
+
27
+ | Tool | What it does |
28
+ | --- | --- |
29
+ | `notifySend` | Sends a notification through a specified channel or the highest-priority available channel. |
30
+ | `notifyBroadcast` | Broadcasts a notification to all registered channels or a specified subset. |
31
+ | `notifySchedule` | Schedules, cancels, or lists pending notifications. |
32
+
33
+ ### `notifySend`
34
+
35
+ | Parameter | Type | Required | Description |
36
+ | --- | --- | --- | --- |
37
+ | `channel` | `string` | No | Target channel id. If omitted, the highest-priority channel is used. |
38
+ | `message` | `string` | Yes | Notification body text. |
39
+ | `subject` | `string` | No | Optional subject or title for the notification. |
40
+ | `metadata` | `object` | No | Arbitrary metadata forwarded to the channel. |
41
+
42
+ ### `notifyBroadcast`
43
+
44
+ | Parameter | Type | Required | Description |
45
+ | --- | --- | --- | --- |
46
+ | `message` | `string` | Yes | Notification body text. |
47
+ | `subject` | `string` | No | Optional subject or title for the notification. |
48
+ | `channels` | `array` of `string` | No | Subset of channel ids to target. If omitted, all registered channels are used. |
49
+ | `metadata` | `object` | No | Arbitrary metadata forwarded to every channel. |
50
+
51
+ ### `notifySchedule`
52
+
53
+ | Parameter | Type | Required | Description |
54
+ | --- | --- | --- | --- |
55
+ | `action` | `string`, enum: `schedule`, `cancel`, `list` | Yes | Action to perform: "schedule" to create, "cancel" to remove, or "list" to view pending notifications. |
56
+ | `channel` | `string` | No | Target channel id (used with "schedule" action). |
57
+ | `message` | `string` | No | Notification body text (required for "schedule" action). |
58
+ | `subject` | `string` | No | Optional subject or title (used with "schedule" action). |
59
+ | `sendAt` | `string` | No | ISO 8601 timestamp for when to send (required for "schedule" action). |
60
+ | `scheduleId` | `string` | No | Schedule id to cancel (required for "cancel" action). |
61
+
62
+ ## Notes
63
+
64
+ - The factory reads no options, secrets, or environment variables. It creates a service with an empty channel registry and does not expose that service in the returned pack.
65
+ - The exported `NotificationService` supports `registerChannel`, `unregisterChannel`, and `listChannels`. A channel supplies `id`, `name`, `priority`, and a `sendFn` callback. The exported tool classes accept a service instance in their constructors.
66
+ - Sending invokes the channel's `sendFn` with the message, subject, and metadata. A missing channel makes `notifySend` return `success: false`. With no registered channels, sending fails with "No notification channels registered".
67
+ - Broadcast sends to channels sequentially, skips unknown ids in a requested subset, and fails if no target channels remain.
68
+ - Channel callback failures appear as `delivered: false` with an error in the returned data. The send and broadcast tools still return `success: true` when the service returns those delivery results.
69
+ - Scheduling stores notifications in memory and uses `setTimeout`. A past `sendAt` triggers delivery without waiting. Deactivation cancels and clears pending notifications.
70
+ - The schedule action checks for `message` and `sendAt`; the cancel action checks for `scheduleId`. These fields remain optional in the input schema.
71
+ - Scheduled delivery failures are swallowed, and the pending entry is removed after the delivery attempt.
72
+
73
+ ## License
74
+
75
+ Apache-2.0
package/manifest.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "$schema": "https://agentos.sh/schemas/extension-manifest-v1.json",
3
3
  "id": "com.framers.communications.notifications",
4
4
  "name": "Notifications Extension",
5
- "version": "0.1.3",
5
+ "version": "0.1.4",
6
6
  "description": "Unified multi-channel notification router — send, broadcast, and schedule notifications across all configured channels.",
7
7
  "categories": ["communications", "notifications"],
8
8
  "platforms": [],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@framers/agentos-ext-notifications",
3
- "version": "0.1.3",
3
+ "version": "0.1.4",
4
4
  "description": "Unified multi-channel notification router for AgentOS — send, broadcast, and schedule notifications across all configured channels.",
5
5
  "license": "Apache-2.0",
6
6
  "main": "dist/index.js",
@@ -13,7 +13,7 @@
13
13
  "@framers/agentos": ">=0.10.40"
14
14
  },
15
15
  "devDependencies": {
16
- "@framers/agentos": "^0.13.40",
16
+ "@framers/agentos": "^0.13.47",
17
17
  "@types/node": "^20.0.0",
18
18
  "typescript": "^5.0.0",
19
19
  "vitest": "^3.2.7"