@narumitw/pi-notify 0.2.0 → 0.4.0
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.
- package/README.md +44 -16
- package/docs/settings.md +319 -5
- package/package.json +15 -2
- package/src/destination-ui.ts +129 -0
- package/src/menu.ts +497 -60
- package/src/metadata.ts +25 -13
- package/src/notify.ts +3 -3
- package/src/provider.ts +82 -1
- package/src/providers/bark.ts +49 -0
- package/src/providers/discord.ts +66 -0
- package/src/providers/gotify.ts +121 -0
- package/src/providers/http.ts +125 -0
- package/src/providers/line.ts +91 -0
- package/src/providers/ntfy.ts +94 -0
- package/src/providers/pushover.ts +47 -0
- package/src/providers/slack.ts +132 -0
- package/src/providers/teams.ts +156 -0
- package/src/{telegram.ts → providers/telegram.ts} +40 -6
- package/src/providers/webhook.ts +48 -0
- package/src/providers.ts +24 -0
package/README.md
CHANGED
|
@@ -4,18 +4,21 @@
|
|
|
4
4
|
[](https://pi.dev)
|
|
5
5
|
[](./LICENSE)
|
|
6
6
|
|
|
7
|
-
Send Telegram
|
|
7
|
+
Send reminders through Telegram, Gotify, Slack, ntfy, Pushover, Discord, Bark, LINE, Microsoft Teams Workflows, or a Generic webhook when Pi stops automatic work.
|
|
8
8
|
|
|
9
9
|
## ✨ Features
|
|
10
10
|
|
|
11
|
-
- Notify
|
|
11
|
+
- Notify Telegram chats and forum topics, Gotify applications, Slack or Discord channels, ntfy topics, Pushover users, Bark devices, LINE recipients, Teams Workflows, or your own webhook.
|
|
12
|
+
- Select multiple destinations across all ten providers.
|
|
12
13
|
- Identify the computer, session, repository, branch, and worktree without forwarding conversations.
|
|
13
14
|
- Choose immediate notifications or reminders after terminal inactivity.
|
|
14
15
|
- Configure and test destinations through a masked, menu-first setup flow.
|
|
15
16
|
|
|
17
|
+
Telegram uses bold titles and repository names, with inline monospace for branches, paths, and session IDs. Entity-based formatting keeps punctuation literal without Markdown or HTML parsing. Confirmation previews remain plain text.
|
|
18
|
+
|
|
16
19
|
## 📦 Install
|
|
17
20
|
|
|
18
|
-
Extensions run with Pi's permissions. Enable this extension only if the notification metadata may leave your computer.
|
|
21
|
+
Extensions run with Pi's permissions. Enable this extension only if the notification metadata may leave your computer. Notification tokens, device keys, LINE recipient IDs, and complete Slack, Discord, Teams, and Generic webhook URLs are private values stored in a private User settings file, not Project settings.
|
|
19
22
|
|
|
20
23
|
From a local checkout, run these commands from the repository root:
|
|
21
24
|
|
|
@@ -36,13 +39,21 @@ Restart Pi or run `/reload` after persistent installation. The extension uses Pi
|
|
|
36
39
|
|
|
37
40
|
## 🚀 Quick start
|
|
38
41
|
|
|
39
|
-
|
|
42
|
+
1. Subscribe to a topic in your ntfy client. A topic name is not access control: configure [server authentication and topic permissions](https://docs.ntfy.sh/config/#access-control) before sending private metadata. Public topics can expose messages and permit unwanted publishers.
|
|
43
|
+
2. Run `/notify`, open destination management, and add an ntfy destination. Enter the topic. In the review, set your server base URL, an optional access token in the masked input, and an optional priority from 1 to 5. Clear priority to use the server default.
|
|
44
|
+
3. Choose Save and use to save and select the destination for User notifications, or Save only to store it without selecting it. Use Send test to preview the metadata and confirm one external request.
|
|
45
|
+
|
|
46
|
+
Automatic notifications are on by default, so the next eligible settled work period sends a reminder. Settings lets you pause delivery or change selections. Existing Off settings and explicit Project selections are preserved. See [provider setup and revocation](./docs/settings.md#provider-setup-and-revocation) for Telegram, Gotify, ntfy, Pushover, Discord, Bark, and Generic webhook setup.
|
|
47
|
+
|
|
48
|
+
For Slack, create a [Slack app](https://api.slack.com/apps), enable Incoming Webhooks, and choose Add New Webhook to Workspace. Authorize the channel that must receive notifications and copy its webhook URL. Enter it only in the masked setup input or User settings, never in Pi chat. The installation fixes the channel; a destination cannot override it. See [Slack setup and revocation](./docs/settings.md#slack-setup-and-revocation).
|
|
40
49
|
|
|
41
|
-
|
|
50
|
+
For Microsoft Teams, create a Workflows flow with **When a Teams webhook request is received**, select **Anyone** authentication, and configure its downstream chat/channel action. Paste the current generated URL only into the masked input or User settings. The integration has not been verified live; HTTP 202 means trigger acceptance, not a successful Teams post. Check workflow run history and the receiving chat/channel after a confirmed test. See [Teams setup and revocation](./docs/settings.md#teams-setup-and-revocation).
|
|
51
|
+
|
|
52
|
+
For LINE, enable Messaging API on a LINE Official Account and obtain a channel access token and eligible user, group, or room ID. `/notify` accepts both in masked inputs. Delivery consumes the account's applicable message allowance; quotas and plans vary by region. LINE Notify is not supported. See [LINE setup and revocation](./docs/settings.md#line-setup-and-revocation).
|
|
42
53
|
|
|
43
54
|
## 💬 Commands
|
|
44
55
|
|
|
45
|
-
`/notify` opens destination management, Settings, Status, Help, and confirmed test delivery in TUI mode. It accepts no arguments. Settings changes save immediately; closing the screen does not undo them. Destination edits remain unsaved until confirmation. Escape goes back; Ctrl+C closes the flow. Cancelling a running test closes the menu and cannot recall a message already accepted by
|
|
56
|
+
`/notify` opens destination management, Settings, Status, Help, and confirmed test delivery in TUI mode. It accepts no arguments. Settings changes save immediately; closing the screen does not undo them. Destination edits remain unsaved until confirmation. Escape goes back; Ctrl+C closes the flow. Cancelling a running test closes the menu and cannot recall a message already accepted by the provider.
|
|
46
57
|
|
|
47
58
|
RPC receives manual configuration instructions instead of a custom terminal screen. Print and JSON reject interactive setup. Automatic delivery is independent of the menu and requires no model tool or prompt changes.
|
|
48
59
|
|
|
@@ -60,10 +71,12 @@ Notifications default to enabled, with immediate mode and a stored inactivity du
|
|
|
60
71
|
"targetIds": ["personal"],
|
|
61
72
|
"destinations": {
|
|
62
73
|
"personal": {
|
|
63
|
-
"provider": "
|
|
64
|
-
"label": "Personal
|
|
65
|
-
"
|
|
66
|
-
"
|
|
74
|
+
"provider": "ntfy",
|
|
75
|
+
"label": "Personal ntfy",
|
|
76
|
+
"serverUrl": "https://ntfy.sh",
|
|
77
|
+
"topic": "replace-with-your-topic",
|
|
78
|
+
"accessToken": "<access-token>",
|
|
79
|
+
"priority": 3
|
|
67
80
|
}
|
|
68
81
|
}
|
|
69
82
|
}
|
|
@@ -73,24 +86,39 @@ See the bundled [settings and behavior reference](./docs/settings.md) for accept
|
|
|
73
86
|
|
|
74
87
|
## 🔒 Security and privacy
|
|
75
88
|
|
|
76
|
-
Notifications send the operating-system hostname, session name and ID, working directory, available Git repository/worktree/branch, elapsed time, and settlement timestamp to the selected
|
|
89
|
+
Notifications send the operating-system hostname, session name and ID, working directory, available Git repository/worktree/branch, elapsed time, and settlement timestamp to the selected notification services or webhook endpoints. Gotify messages are visible to the user who owns the application; Slack messages are visible to people with access to the installed channel. Paths shorten the home prefix to `~` when possible, but names and paths can still disclose private information. They describe the host running Pi, which can differ from your SSH client computer.
|
|
90
|
+
|
|
91
|
+
No prompts, assistant answers, code, tool output, Git remotes, or raw provider errors are sent. Dynamic metadata is bounded and terminal controls are removed; `@` is replaced with `@` to avoid accidental mentions. Telegram link previews are disabled. Gotify sends plain text without Markdown extras. Slack uses `plain_text` blocks without mention or link expansion and a generic fallback. Slack desktop notifications can still show metadata from the blocks. Discord disables mention parsing and link previews, but does not suppress notifications. Credential values, LINE recipient IDs, and complete Slack, Discord, Teams, and Generic webhook URLs never appear in review, preview, status, or error output. LINE receives the selected recipient ID and metadata through its Messaging API; members of a selected group or room can read the message. LINE clients can automatically link URLs in plain text. Teams receives a fixed Adaptive Card with literal text and no actions, images, or mentions; client automatic links are not guaranteed to be suppressed. People with access to the workflow's destination chat/channel can read its metadata. POSIX settings writes use `0600` permissions and temporary-file-plus-rename publication. JavaScript memory is not secure credential storage; revoke exposed tokens through BotFather or your Gotify server, or revoke the webhook in Slack before replacing its User setting. Removing a saved destination does not revoke its credential. See [provider revocation instructions](./docs/settings.md#provider-setup-and-revocation) for the new services.
|
|
92
|
+
|
|
93
|
+
Gotify sends its application token in the `X-Gotify-Key` header, never in the URL. Use HTTPS: HTTP is supported for private self-hosted servers but sends the token and metadata without encryption. Server URLs cannot contain credentials, query strings, or fragments. Redirects are rejected.
|
|
77
94
|
|
|
78
|
-
|
|
95
|
+
Prefer HTTPS for ntfy, Bark, and Generic webhooks too: HTTP sends credentials and metadata without encryption. User-configured endpoints can reach local/private addresses on the Pi host's network; Project settings cannot supply endpoints. ntfy topic secrecy is not access control, and access tokens have the user's full access. Configure server ACLs. Bark JSON keeps keys and messages out of URLs but does not prevent the official server from logging request bodies. Do not send metadata to servers you do not trust.
|
|
79
96
|
|
|
80
97
|
## 🚧 Limitations
|
|
81
98
|
|
|
82
|
-
|
|
99
|
+
The ten listed providers are built in; third-party provider plugins are not loaded. Slack supports commercial Incoming Webhooks at `https://hooks.slack.com/services/...` only, with the channel selected during installation. GovSlack, channel overrides, OAuth, bot tokens, replies, and file uploads are not supported. No Slack SDK or extension-specific environment variables are required. Gotify uses application tokens, not client tokens or user passwords. It sends messages only; it does not subscribe to messages or manage applications.
|
|
100
|
+
|
|
101
|
+
Teams supports commercial Workflows with Anyone authentication only, without an Authorization header. The workflow owns routing; account permissions, workflow owners/co-owners, tenant policy, and Workflows availability affect delivery. Legacy Office connectors, `logic.azure.com`, government clouds, tenant-authenticated triggers, OAuth, and channel overrides are not supported. The fixed Adaptive Card 1.2 uses literal `RichTextBlock`/`TextRun` text without Markdown. Encoded JSON is capped locally at 24,000 UTF-8 bytes, with Unicode-safe clipping; this is not a downstream rendering guarantee. Only HTTP 202 after a bounded response read counts as trigger acceptance. This explicit client policy awaits live interoperability verification, not a claim of a universal Microsoft URL or response contract. See [Teams URL, payload, and acceptance limits](./docs/settings.md#microsoft-teams).
|
|
102
|
+
|
|
103
|
+
LINE sends one plain-text Messaging API push, clipped to 5,000 UTF-16 code units. It requires an eligible recipient and account allowance; HTTP acceptance does not prove receipt, including when the recipient blocked the account. It does not discover recipient IDs, receive events, manage accounts, or support replies, broadcast, silent delivery, or LINE Notify. See [LINE fields and delivery limits](./docs/settings.md#line).
|
|
104
|
+
|
|
105
|
+
Pushover uses normal priority only, without emergency delivery, acknowledgement, or retry parameters. Discord supports official webhooks for normal text channels, not forum/media channels or thread selection. ntfy and Generic webhooks support no authentication or Bearer authentication only; Bark supports its device key, not native server Basic authentication. No custom headers, templates, scripts, or extension-specific environment variables are supported. See [provider fields and limits](./docs/settings.md#new-provider-fields) for exact URL, credential, and payload bounds.
|
|
106
|
+
|
|
107
|
+
Telegram messages are limited to 4,096 UTF-16 code units without splitting a Unicode code point; longer messages end with an unformatted ellipsis. Gotify sends the title and body in separate fields; server and proxy limits apply. Slack clips plain-text blocks to its documented limits without splitting Unicode code points; see the [payload and delivery reference](./docs/settings.md#work-periods-and-delivery).
|
|
83
108
|
|
|
84
109
|
Inactivity means no input reached this extension, not proof that you are away. Pi handles fullscreen focus, mouse, scrolling, and search before extension input listeners. Those actions do not reliably cancel a reminder. Reading without typing can still produce one. Type a key that reaches the editor to cancel a pending reminder. Focus or mouse events count only if Pi forwards them; terminal support alone is not sufficient. This extension does not change Pi's listener order, enable focus reporting, or detect screen locks. RPC, print, and JSON cannot observe terminal input, so inactivity mode delivers at settlement instead.
|
|
85
110
|
|
|
86
|
-
Notification delivery is best effort with one attempt and a 10-second request
|
|
111
|
+
Notification delivery is best effort with one attempt and a 10-second deadline covering the request and response body, capped at 65,536 bytes. There is no automatic retry, persistent queue, or replay after reload. Accepted means the provider accepted a message, not that someone read it. Rate limits can reject rapid runs; Status reports a safe error code and available retry-after time. Immediate shutdown can cancel an in-flight notification, especially in a short-lived headless session.
|
|
87
112
|
|
|
88
113
|
Manual aborts and interactive confirmation prompts do not notify. `agent_settled` means Pi will not continue automatically, not that the requested task succeeded. Preflight errors that do not produce a settled work period cannot generate a completion notification. No cooldown suppresses distinct eligible work periods.
|
|
89
114
|
|
|
115
|
+
Before reverting to a version without Teams, remove its IDs from every affected explicit Project selection, User selections, and all saved Teams destinations while this version remains installed. Revoke exposed or unused workflow URLs separately. Before reverting to a version without LINE, remove its destination IDs from explicit Project selections, User selections, and saved destinations while this version is installed; unselected unsupported destinations also disable older routing. Revoke credentials through LINE separately. Before reverting to a version without the five new providers, remove their IDs from every affected Project selection, User selections, and saved destinations while the current version is installed. Before reverting to a version without Slack support, remove Slack IDs from User and Project selections and remove the Slack destinations while the current version is installed. Older versions disable automatic delivery for unsupported destinations, even when unselected. See [rollback steps](./docs/settings.md#persistence-and-recovery).
|
|
116
|
+
|
|
90
117
|
## 🗂️ Package layout
|
|
91
118
|
|
|
92
119
|
- `src/index.ts`: Pi entrypoint forwarding to `src/notify.ts`.
|
|
93
|
-
- `src/`: session coordination, metadata, settings, menu, provider contract
|
|
120
|
+
- `src/`: session coordination, metadata, settings, menu, and provider contract.
|
|
121
|
+
- `src/providers/`: provider-specific transports and shared bounded HTTP handling.
|
|
94
122
|
- `docs/`: installed settings and behavior reference.
|
|
95
123
|
- `test/`: repository-only deterministic tests.
|
|
96
124
|
|
|
@@ -98,7 +126,7 @@ The package publishes TypeScript source, documentation, and its license. It does
|
|
|
98
126
|
|
|
99
127
|
## 🔎 Keywords
|
|
100
128
|
|
|
101
|
-
Pi coding agent, Telegram bot, completion notification, inactivity reminder,
|
|
129
|
+
Pi coding agent, Telegram bot, Gotify, Slack Incoming Webhooks, ntfy, Pushover, Discord webhook, Bark, LINE Messaging API, Microsoft Teams Workflows, Generic webhook, self-hosted notifications, completion notification, inactivity reminder, Git worktree.
|
|
102
130
|
|
|
103
131
|
## 📄 License
|
|
104
132
|
|
package/docs/settings.md
CHANGED
|
@@ -14,21 +14,308 @@ Use `/notify` for setup or edit the canonical user JSON file. Settings load on s
|
|
|
14
14
|
|
|
15
15
|
Destination IDs contain 1–64 ASCII letters, digits, underscores, or hyphens, starting with a letter or digit; `constructor`, `prototype`, and `__proto__` are reserved. The menu creates IDs automatically.
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
Telegram setup requires a bot token and chat ID; Gotify setup requires an application token and server URL; Slack setup requires a complete Incoming Webhook URL. The other providers use the [fields below](#new-provider-fields). Add destinations through the provider-choice screen in `/notify`. The menu generates a label and opens a review for edits before saving. Editing an existing destination opens the same review with its current values. Destination changes take effect only after confirmation. For a new destination, Save and use adds it to User `targetIds` in the same atomic save; Save only stores it without selecting it. Editing an existing destination preserves its selection state. Explicit Project selections and saved `enabled: false` values are unchanged. Automatic notifications default to On; Off pauses automatic delivery but still allows manual tests. No delivery occurs without a selected destination.
|
|
18
18
|
|
|
19
19
|
Each Telegram destination has `provider: "telegram"`, a nonempty `label` of at most 128 characters, `botToken`, a numeric string `chatId`, and optional positive safe-integer `messageThreadId`. A group or supergroup ID can be negative. Store IDs as strings, not JSON numbers. Forum topic IDs use Telegram's `message_thread_id` field. Other Telegram chat products with additional required fields are not supported.
|
|
20
20
|
|
|
21
|
+
Each Gotify destination has `provider: "gotify"`, a nonempty `label` of at most 128 characters, `serverUrl`, `appToken`, and optional `priority`. Use an application token created in the server's Apps tab, not a client token or password. Tokens must contain 1–512 printable ASCII characters without spaces. Server URLs must be absolute HTTP(S) URLs, at most 2048 characters before and after URL normalization, without whitespace, control characters, backslashes, credentials, query strings, or fragments. Include any reverse-proxy base path; do not append `/message`. Trailing slashes are removed on save. HTTP is supported for self-hosted deployments but does not encrypt credentials or metadata; prefer HTTPS. Priority must be a safe integer (including zero or negative values). Leave it unset to use the application's default priority; clear the field in review to restore that default.
|
|
22
|
+
|
|
23
|
+
```json
|
|
24
|
+
{
|
|
25
|
+
"targetIds": ["gotify"],
|
|
26
|
+
"destinations": {
|
|
27
|
+
"gotify": {
|
|
28
|
+
"provider": "gotify",
|
|
29
|
+
"label": "Personal Gotify",
|
|
30
|
+
"serverUrl": "https://push.example.com/gotify",
|
|
31
|
+
"appToken": "<application-token>",
|
|
32
|
+
"priority": 5
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Each Slack destination has `provider: "slack"`, a nonempty `label` of at most 128 characters, and `webhookUrl`. The complete URL is a credential and belongs only in the canonical User file. The channel comes from the webhook installation, not the label or a settings field. URLs must be at most 2048 characters and match `https://hooks.slack.com/services/T[A-Z0-9]+/B[A-Z0-9]+/[A-Za-z0-9]+` exactly: a `T` workspace segment, a `B` installation segment, and an alphanumeric secret. Ports, URL credentials, query strings, fragments, redirects, alternate hosts, whitespace, control characters, backslashes, and encoded or normalized URL alternatives are rejected. GovSlack is not supported.
|
|
39
|
+
|
|
40
|
+
A User file can select all ten providers together. For example, with existing `personal` Telegram and `gotify` destinations, add a Slack destination and select their IDs:
|
|
41
|
+
|
|
42
|
+
```json
|
|
43
|
+
{
|
|
44
|
+
"targetIds": ["personal", "gotify", "build-channel"],
|
|
45
|
+
"destinations": {
|
|
46
|
+
"build-channel": {
|
|
47
|
+
"provider": "slack",
|
|
48
|
+
"label": "Build channel",
|
|
49
|
+
"webhookUrl": "https://hooks.slack.com/services/<workspace>/<installation>/<secret>"
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
This fragment shows the Slack addition, not a replacement for the complete User document. Retain the existing destination entries; replace the placeholder URL with the exact URL from Slack. Never put it in Project settings, source control, or Pi chat. No SDK, OAuth flow, bot token, or extension-specific environment variable is used. Saved destinations keep their provider; create a new destination to change providers.
|
|
56
|
+
|
|
21
57
|
Resolve defaults, User fields, then trusted Project overrides. Project arrays replace rather than merge. Project files cannot define destinations or credentials. Unknown provider IDs do not fall back to Telegram. Invalid fields, unreadable files, unsupported destinations, or missing selected IDs produce diagnostics and disable automatic delivery until repaired; no partial routing is attempted.
|
|
22
58
|
|
|
23
59
|
Project Settings show inherited values and allow restoring inheritance. Removing a destination clears its User selection atomically, but is blocked if the current trusted Project explicitly selects it. Change that Project selection first. Other projects are not edited; repair their selected IDs before enabling notifications there.
|
|
24
60
|
|
|
61
|
+
## New provider fields
|
|
62
|
+
|
|
63
|
+
All destinations require `provider` and a nonempty `label` of at most 128 characters. Destinations, addresses, and credentials belong only in `<getAgentDir()>/pi-notify.json`, normally `~/.pi/agent/pi-notify.json`. Trusted Project files at `<workspace>/.pi/pi-notify.json` can change policy or select existing User destination IDs, but cannot define endpoints or secrets.
|
|
64
|
+
|
|
65
|
+
| Provider | Required fields besides `provider` and `label` | Optional fields |
|
|
66
|
+
| --- | --- | --- |
|
|
67
|
+
| `ntfy` | `serverUrl`, `topic` | `accessToken`, `priority` |
|
|
68
|
+
| `pushover` | `appToken`, `userKey` | None |
|
|
69
|
+
| `discord` | `webhookUrl` | None |
|
|
70
|
+
| `bark` | `serverUrl`, `deviceKey` | None |
|
|
71
|
+
| `webhook` | `webhookUrl` | `bearerToken` |
|
|
72
|
+
| `line` | `channelAccessToken`, `recipientId` | None |
|
|
73
|
+
| `teams` | `webhookUrl` | None |
|
|
74
|
+
|
|
75
|
+
For ntfy and Bark, enter the server base URL including any reverse-proxy base path. Do not append the topic or `/push`. Generic `webhookUrl` is the complete receiving endpoint. These configurable URLs must be absolute HTTP(S) URLs, at most 2048 characters both before and after normalization. URL user information, whitespace, control characters, encoded controls, backslashes (including encoded backslashes), malformed percent escapes, query strings, and fragments are rejected. Bark server bases remove trailing slashes before appending `/push`. ntfy publish URLs and Generic webhook endpoints preserve trailing slashes because they can select a different route. Literal or encoded dot segments and noncanonical numeric IPv4 aliases are rejected instead of silently selecting a different path or host. Prefer HTTPS; HTTP does not encrypt credentials or metadata. Explicit local/private addresses are allowed and can reach the Pi host's network. Use only trusted endpoints.
|
|
76
|
+
|
|
77
|
+
The ntfy `accessToken`, Bark `deviceKey`, and Generic `bearerToken` each have a local limit of 1–512 printable ASCII characters without spaces. This is a header/key safety limit, not a promise that a service accepts every such value. Omit optional credentials in JSON; in review, leave the replacement input empty to clear them. Empty strings are not stored credentials. ntfy and Generic webhooks support only anonymous or Bearer authentication, not Basic, URL credentials, arbitrary headers, or query-based authentication. No custom templates, scripts, or extension-specific environment variables are supported.
|
|
78
|
+
|
|
79
|
+
### ntfy
|
|
80
|
+
|
|
81
|
+
`topic` must match `[-_A-Za-z0-9]{1,64}`. Reserved names are `docs`, `static`, `file`, `app`, `metrics`, `account`, `settings`, `signup`, `login`, and `v1`; the check is case-sensitive. A self-hosted server can forbid additional names. `priority`, when present, must be an integer from 1 to 5; an omitted or cleared priority uses the server default.
|
|
82
|
+
|
|
83
|
+
The transport sends JSON directly to the normalized server base URL, with `topic`, `title`, `message`, and optional `priority`. A configured `accessToken` is sent only as a Bearer header. Title and body are clipped to 1024 and 4096 UTF-8 bytes. The complete encoded JSON request is also capped at 8192 bytes; escaping can reduce the available body length. Only HTTP 200 with a message object counts as accepted. That object must have a nonempty string `id`, positive safe-integer `time`, `event: "message"`, the expected `topic`, and a string `message`.
|
|
84
|
+
|
|
85
|
+
Topic secrecy is not access control. Without server authentication and topic permissions, public topics can expose metadata and allow unwanted publishers. An ntfy access token has the user's full access; it is not a topic-scoped credential. Configure server ACLs, use a suitably restricted user, and protect the token.
|
|
86
|
+
|
|
87
|
+
### Pushover
|
|
88
|
+
|
|
89
|
+
`appToken` and `userKey` must each contain exactly 30 ASCII alphanumeric characters. Pushover uses the fixed HTTPS endpoint `https://api.pushover.net/1/messages.json`; no server URL is configurable. It sends JSON fields `token`, `user`, `title`, `message`, and `priority: 0`. There is no emergency priority, acknowledgement, retry parameter, or configurable priority.
|
|
90
|
+
|
|
91
|
+
The local title and body caps are 250 and 1024 UTF-16 code units. These are conservative bounds for the service's character limits; astral characters use two code units. Only HTTP 200 with numeric JSON `status: 1` counts as accepted.
|
|
92
|
+
|
|
93
|
+
### Discord
|
|
94
|
+
|
|
95
|
+
`webhookUrl` must use one of these exact official endpoint shapes, with a positive decimal webhook ID (no leading zero, at most 20 digits and at most 18446744073709551615) and a nonempty alphanumeric, underscore, or hyphen token:
|
|
96
|
+
|
|
97
|
+
```text
|
|
98
|
+
https://discord.com/api/webhooks/{id}/{token}
|
|
99
|
+
https://discord.com/api/v10/webhooks/{id}/{token}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
The complete URL is a credential. Alternate hosts, ports, URL credentials, queries, fragments, encoded or normalized alternatives, controls, and backslashes are rejected. The transport adds `wait=true` internally, but configured URLs must have no query string.
|
|
103
|
+
|
|
104
|
+
Discord receives title and body as `content`, clipped to 2000 UTF-16 code units. Requests set `allowed_mentions: { "parse": [] }` and `flags: 4` (`SUPPRESS_EMBEDS`), even for direct provider callers. This prevents mention parsing and link previews; it does not suppress notifications. A descriptive User-Agent identifies the integration. Only HTTP 200 with a Message response containing valid positive decimal `id` and `channel_id` values under the same ID bound and an integer `type` counts as accepted. Normal text-channel webhooks are supported; forum/media channels and thread selection are not.
|
|
105
|
+
|
|
106
|
+
### Bark
|
|
107
|
+
|
|
108
|
+
`serverUrl` can be `https://api.day.app` or a self-hosted server base, including a reverse-proxy path. JSON is sent to `<serverUrl>/push` with `device_key`, `title`, and `body`. The key and message are never placed in a URL path or query. The device key is the only supported Bark credential; there is no Bark bearer field. Servers that require Bark's native Basic authentication are not supported. A separate proxy is outside this integration's contract.
|
|
109
|
+
|
|
110
|
+
Local title and body caps are 256 and 2048 UTF-8 bytes. The encoded `{title,body}` object is capped at 3000 bytes to leave space within Apple's 4096-byte APNs envelope. These are conservative local limits, not universal server limits. Only HTTP 200 with numeric JSON `code: 200` counts as accepted. JSON delivery avoids URL exposure but does not prevent the official Bark server from logging request bodies, including device keys and metadata.
|
|
111
|
+
|
|
112
|
+
### Generic webhook
|
|
113
|
+
|
|
114
|
+
`webhookUrl` is masked in full, even without a token. Optional `bearerToken` is sent as `Authorization: Bearer <token>`. The fixed JSON payload contains only:
|
|
115
|
+
|
|
116
|
+
```json
|
|
117
|
+
{
|
|
118
|
+
"id": "notification-id",
|
|
119
|
+
"title": "Pi notification title",
|
|
120
|
+
"body": "Notification metadata",
|
|
121
|
+
"settledAt": 1792281600000
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
`settledAt` is Unix epoch milliseconds, not seconds. No internal emphasis, destination credentials, or configurable fields are added. Any HTTP 2xx response counts as endpoint acceptance, including empty or non-JSON responses, after the bounded response read completes. This is not proof of downstream delivery. An oversized or stalled 2xx response body can still fail with `response` or `timeout`.
|
|
126
|
+
|
|
127
|
+
### LINE
|
|
128
|
+
|
|
129
|
+
Use `provider: "line"`, a `channelAccessToken`, and a `recipientId`. LINE Notify tokens and public LINE IDs are not accepted. The token must contain 1–8192 characters in the Bearer token alphabet (`A–Z`, `a–z`, digits, `-._~+/`, with optional trailing `=`), without whitespace. The 8192-character cap is a local header safety bound, not a LINE service limit. A user ID must match `U[0-9a-f]{32}`. Group and room IDs must start with `C` or `R`; the provider accepts an opaque suffix of 1–128 printable ASCII characters without spaces. Both the ASCII restriction and suffix cap are local safety policies, not a claimed LINE group/room ID grammar. Use the complete ID from LINE, not a shortened example. The token and raw recipient ID stay hidden in all menus, previews, Status, and errors.
|
|
130
|
+
|
|
131
|
+
The transport posts one `{ "type": "text", "text": "..." }` message to `https://api.line.me/v2/bot/message/push`, with the recipient in `to` and the token only in the Authorization header. Title and metadata body are combined, terminal controls removed, and text clipped to 5,000 UTF-16 code units, including an ellipsis when clipped, without splitting Unicode code points. No mention objects, formatting, silent-delivery fields, or emphasis offsets are sent. Client automatic links are not suppressed.
|
|
132
|
+
|
|
133
|
+
Only HTTP 200 with a legacy empty JSON object or a valid current `sentMessages` response counts as accepted. The current response must contain 1–5 message objects with a nonempty string or nonnegative integer `id`; `quoteToken` is an optional string. Empty/non-JSON, unrelated, malformed, or oversized success bodies fail safely. HTTP 429 can indicate a rate limit or an exhausted account allowance; retry-after is diagnostic only and no retry occurs.
|
|
134
|
+
|
|
135
|
+
For example, add this fragment to the existing User document and include `line-personal` in `targetIds` if automatic notifications should use it. Replace both private placeholders outside Pi chat; do not replace unrelated destinations or settings.
|
|
136
|
+
|
|
137
|
+
```json
|
|
138
|
+
{
|
|
139
|
+
"destinations": {
|
|
140
|
+
"line-personal": {
|
|
141
|
+
"provider": "line",
|
|
142
|
+
"label": "Personal LINE",
|
|
143
|
+
"channelAccessToken": "<channel-access-token>",
|
|
144
|
+
"recipientId": "<complete-user-group-or-room-id>"
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Recipient eligibility and message allowances apply. A user generally must be a friend of the Official Account or have messaged it in a one-to-one chat within the past seven days; group/room delivery requires the account to participate. HTTP 200 does not prove receipt: blocked or deleted accounts and ineligible users can still produce acceptance without delivery. Monthly allowances, pricing, and group message counting depend on the account's region and plan. Check the account before enabling automatic notifications. The extension does not obtain recipient IDs, run an inbound webhook, inspect quota, or manage account access.
|
|
151
|
+
|
|
152
|
+
### Microsoft Teams
|
|
153
|
+
|
|
154
|
+
Use `provider: "teams"`, a `label`, and `webhookUrl`. This supports the commercial Teams Workflows trigger **When a Teams webhook request is received**, with **Anyone** authentication only. No Authorization header is sent. The complete signed URL, including its host, path, and query, is a credential. It is never shown in menus, reviews, test previews, Status, or errors. Keep it only in User settings; never paste it into Pi chat or Project settings.
|
|
155
|
+
|
|
156
|
+
**The current Teams integration has not been verified live.** The following is an explicit supported client policy awaiting live interoperability verification, not a complete Microsoft endpoint grammar or a resolved global response contract. Microsoft documents trigger authentication, payload examples, and URL migration, but observed URL examples do not define every possible service URL.
|
|
157
|
+
|
|
158
|
+
The local validator accepts only:
|
|
159
|
+
|
|
160
|
+
- A URL of at most 8192 characters, with the exact lowercase `https://` scheme and one or more lowercase DNS labels before `.environment.api.powerplatform.com`. Each label contains 1–63 lowercase ASCII letters, digits, or hyphens and starts and ends with a letter or digit; the complete hostname is at most 253 characters. Only an omitted port or explicit `:443` is allowed.
|
|
161
|
+
- One of these literal paths, without a trailing slash or encoded/normalized alternatives:
|
|
162
|
+
|
|
163
|
+
```text
|
|
164
|
+
/powerautomate/automations/direct/workflows/<opaqueID>/triggers/manual/paths/invoke
|
|
165
|
+
/powerautomate/automations/direct/cu/<opaqueRoute>/workflows/<opaqueID>/triggers/manual/paths/invoke
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Each `opaqueID` and `opaqueRoute` must match `[A-Za-z0-9_-]{1,256}`. This is a local safety policy, not a universal Microsoft ID or routing grammar.
|
|
169
|
+
- Exactly four query keys, each present once: literal `api-version=1`, `sp` decoded to `/triggers/manual/run`, literal `sv=1.0`, and `sig` with a nonempty decoded value in the base64/base64url alphabet (`A–Z`, `a–z`, digits, `+`, `/`, `_`, `-`) and at most two trailing `=` padding characters. Query order may vary. Values use percent decoding, not form decoding: `+` remains `+`, not a space. Encoded key names, duplicate keys, unknown keys, and malformed percent escapes or UTF-8 are rejected. The original signed URL is preserved, including escape case, query order, and explicit `:443`; it is not rebuilt from decoded values.
|
|
170
|
+
|
|
171
|
+
Whitespace, controls, backslashes, URL user information, fragments, other ports, malformed encoding, and alternatives that require case or path normalization are rejected. Legacy Office connectors, obsolete `logic.azure.com` endpoints, government clouds, and tenant-authenticated triggers are unsupported. If a current generated URL falls outside this policy, do not edit or reconstruct its signature to make it fit.
|
|
172
|
+
|
|
173
|
+
The request contains a fixed Adaptive Card 1.2 message attachment. `RichTextBlock`/`TextRun` elements carry sanitized title and metadata as literal text; `TextRun` does not support Markdown. No actions, images, user templates, or routing overrides are included. Terminal controls are removed. Provider-neutral metadata replaces `@` with `@`; no mention entities are sent. Client automatic links are not guaranteed to be suppressed. The workflow selects the destination chat/channel, whose members can read the metadata.
|
|
174
|
+
|
|
175
|
+
The entire encoded JSON request is capped locally at 24,000 UTF-8 bytes, including its envelope and JSON escaping. Clipping preserves complete Unicode code points and includes an ellipsis within the budget. This conservative local bound is not proof that every downstream Teams action accepts the rendered card: Microsoft's approximate 28 KB action limit includes rendered elements.
|
|
176
|
+
|
|
177
|
+
Delivery reuses the bounded JSON transport unchanged: one attempt, no retry, redirects rejected, a 10-second total request/response deadline, and a 65,536-byte response-read cap. **Only HTTP 202** counts as trigger acceptance after that read completes. A bounded empty, text, or JSON body is allowed; no response-body meaning is inferred. Other 2xx statuses are not accepted. Oversized or stalled 202 bodies can still fail with `response` or `timeout`. HTTP 429 reports a safe `rate-limit` and an available positive integer `Retry-After`, without retrying. Under [HTTP 202 semantics](https://www.rfc-editor.org/rfc/rfc9110.html#name-202-accepted), acceptance does not establish completed processing. It proves neither that a workflow posted to Teams nor that a recipient read the message; check run history and the receiving chat/channel separately.
|
|
178
|
+
|
|
179
|
+
Add this fragment to the existing User document and include `teams-workflow` in `targetIds` to select it. Replace the placeholder with the exact current generated URL outside Pi chat; preserve unrelated destinations and settings.
|
|
180
|
+
|
|
181
|
+
```json
|
|
182
|
+
{
|
|
183
|
+
"destinations": {
|
|
184
|
+
"teams-workflow": {
|
|
185
|
+
"provider": "teams",
|
|
186
|
+
"label": "Build Teams workflow",
|
|
187
|
+
"webhookUrl": "<current-generated-workflow-url>"
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
No extension OAuth flow, inbound server, SDK, or channel override is needed or supported. See [Teams setup and revocation](#teams-setup-and-revocation) for workflow ownership, permissions, and operational checks.
|
|
194
|
+
|
|
195
|
+
### Mixed User settings example
|
|
196
|
+
|
|
197
|
+
Replace placeholders with real values. `appToken` and `userKey` must meet the Pushover length rule; the Discord URL must be copied from Discord. This fragment does not replace existing Telegram, Gotify, Slack, or unknown settings. Omit optional tokens when using anonymous delivery.
|
|
198
|
+
|
|
199
|
+
```json
|
|
200
|
+
{
|
|
201
|
+
"targetIds": ["ntfy", "pushover", "discord", "bark", "home-hook"],
|
|
202
|
+
"destinations": {
|
|
203
|
+
"ntfy": {
|
|
204
|
+
"provider": "ntfy",
|
|
205
|
+
"label": "Personal ntfy",
|
|
206
|
+
"serverUrl": "https://ntfy.sh",
|
|
207
|
+
"topic": "replace-with-your-topic",
|
|
208
|
+
"accessToken": "<access-token>",
|
|
209
|
+
"priority": 3
|
|
210
|
+
},
|
|
211
|
+
"pushover": {
|
|
212
|
+
"provider": "pushover",
|
|
213
|
+
"label": "Personal Pushover",
|
|
214
|
+
"appToken": "<30-character-application-token>",
|
|
215
|
+
"userKey": "<30-character-user-key>"
|
|
216
|
+
},
|
|
217
|
+
"discord": {
|
|
218
|
+
"provider": "discord",
|
|
219
|
+
"label": "Build channel",
|
|
220
|
+
"webhookUrl": "https://discord.com/api/webhooks/<id>/<token>"
|
|
221
|
+
},
|
|
222
|
+
"bark": {
|
|
223
|
+
"provider": "bark",
|
|
224
|
+
"label": "Personal Bark",
|
|
225
|
+
"serverUrl": "https://api.day.app",
|
|
226
|
+
"deviceKey": "<device-key>"
|
|
227
|
+
},
|
|
228
|
+
"home-hook": {
|
|
229
|
+
"provider": "webhook",
|
|
230
|
+
"label": "Home automation",
|
|
231
|
+
"webhookUrl": "https://automation.example.com/pi-notify",
|
|
232
|
+
"bearerToken": "<bearer-token>"
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
}
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
## Provider setup and revocation
|
|
239
|
+
|
|
240
|
+
Use `/notify` to add a destination, complete its review, and choose Save only or Save and use. Labels are generated automatically and can be changed. Secret inputs are masked; complete Discord, Teams, and Generic webhook URLs remain hidden in lists, reviews, tests, Status, and errors. Optional ntfy tokens and priority, and Generic tokens, can be cleared in review. Send test previews the metadata and requires confirmation before an external request. Unsaved cancellation does not save a draft; cancelling delivery cannot recall an accepted message.
|
|
241
|
+
|
|
242
|
+
### Telegram and Gotify
|
|
243
|
+
|
|
244
|
+
For Telegram, create a bot with [BotFather](https://t.me/BotFather), then start a private conversation with it. After sending a message, obtain the numeric chat ID through the [Bot API](https://core.telegram.org/bots/api#getupdates). Stop other update consumers first; an active webhook prevents `getUpdates` from working. For groups, add the bot and permit it to send messages. Enter the bot token in the masked input, then the chat ID. Set an optional forum topic in review. Revoke an exposed token through BotFather before replacing it.
|
|
245
|
+
|
|
246
|
+
For Gotify, create an application in the server's Apps tab. Enter its application token in the masked input and the server base URL, including any reverse-proxy path, not `/message`. Review the optional priority. See [Gotify setup](https://gotify.net/docs/pushmsg). Revoke an exposed application token through the server and replace it in User settings.
|
|
247
|
+
|
|
248
|
+
### ntfy, Pushover, Discord, Bark, and Generic webhook
|
|
249
|
+
|
|
250
|
+
1. For ntfy, subscribe to a topic with your client and configure server authentication and topic ACLs before sending private metadata. Use `https://ntfy.sh` or your own server base. Add the topic, then review the server, optional access token, and optional priority. Revoke exposed tokens in the ntfy account/server and replace them; changing a public topic name does not establish access control.
|
|
251
|
+
2. For Pushover, register an application in your [Pushover account](https://pushover.net/), obtain its application/API token and your user key, and enter both in the masked inputs. Revoke or reset exposed credentials through Pushover account/application management before replacing them; remove an application if required to invalidate its token.
|
|
252
|
+
3. For Discord, create a webhook for a normal text channel through channel or server integration settings, then paste the complete webhook URL into the masked input. Channel/server permissions can restrict creation. Delete a compromised webhook in Discord and create a replacement; changing a label does not change its channel or revoke its URL.
|
|
253
|
+
4. For Bark, install/register the Bark client, copy its device key, and use `https://api.day.app` or your self-hosted server base. Enter the device key in the masked input. Reset or re-register the device key through the client/server if exposed; verify that the old key no longer works before relying on the replacement.
|
|
254
|
+
5. For a Generic webhook, provision a trusted receiver for the fixed payload and, if required, a Bearer token. Enter the complete endpoint URL and optional token in masked inputs. Revoke/rotate the token at the receiver, or disable/replace a secret endpoint URL if exposed.
|
|
255
|
+
|
|
256
|
+
Keep secrets out of Project files, source control, and Pi chat. Prefer HTTPS and confirm replacements with Send test. Removing or editing a destination does not revoke its old credential. JavaScript memory is not secure credential storage. See the separate [Slack workflow](#slack-setup-and-revocation) for Slack installation and revocation.
|
|
257
|
+
|
|
258
|
+
## Slack setup and revocation
|
|
259
|
+
|
|
260
|
+
1. Create or open an app in [Slack app management](https://api.slack.com/apps) for the commercial workspace that must receive notifications. Workspace policy can require administrator approval.
|
|
261
|
+
2. Enable Incoming Webhooks, choose Add New Webhook to Workspace, select the destination channel, and authorize it. You must belong to a private channel before selecting it. Copy the generated webhook URL; it is specific to that installation and channel.
|
|
262
|
+
3. Run `/notify`, add a Slack destination, and paste the complete URL into the masked input. Review the generated `Slack notifications` label or change it. Reviews show only that the webhook is configured, not its URL or path.
|
|
263
|
+
4. Choose Save only to store without selecting, or Save and use to add the destination to User selections atomically. Existing Off settings and explicit Project selections remain unchanged. Send test shows a metadata preview and requires confirmation before one external request. Closing an unsaved draft does not save it.
|
|
264
|
+
|
|
265
|
+
To change channels, authorize a webhook for the new channel and replace the saved webhook through the destination review, or create a separate destination. The extension cannot override the installed channel, username, or icon. It does not send replies, upload files, or manage Slack apps.
|
|
266
|
+
|
|
267
|
+
Treat an exposed URL as a compromised credential. Revoke or remove that webhook through Slack app management before replacing it in User settings; ask the workspace administrator if you cannot manage the installation. Slack can also revoke leaked webhooks automatically. Merely editing or removing a destination does not revoke the old webhook. Confirm a replacement with Send test. A disabled webhook, archived channel, or workspace restriction can prevent delivery; repair the installation instead of expecting a retry. Cancelling a request cannot recall a message Slack has already accepted.
|
|
268
|
+
|
|
269
|
+
## LINE setup and revocation
|
|
270
|
+
|
|
271
|
+
1. Create a [LINE Official Account](https://developers.line.biz/en/docs/messaging-api/getting-started/) and enable Messaging API from its administration interface. Open the linked channel in LINE Developers Console and obtain a channel access token. Account policy, plan, and region can restrict availability or message allowance.
|
|
272
|
+
2. For personal delivery, add the account as a friend and use your developer-console user ID for the same provider. For groups or rooms, permit the account to join and obtain the full `groupId` or `roomId` from an authorized webhook event through an existing receiver. See [user ID discovery](https://developers.line.biz/en/docs/messaging-api/getting-user-ids/) and [group chats](https://developers.line.biz/en/docs/messaging-api/group-chats/). The extension does not install a receiver or discover IDs. A display name or public LINE ID is not the recipient ID.
|
|
273
|
+
3. Run `/notify`, add a LINE destination, and enter the token and recipient ID in separate masked inputs. Review the generated label. Replace either private value from review; replacement inputs start empty and never display the saved value. Cancellation leaves the draft unsaved.
|
|
274
|
+
4. Choose Save only or Save and use, then Send test. Check the metadata preview before confirming the external request, and check the receiving LINE chat after acceptance. Confirm account allowance and recipient eligibility before expecting automatic delivery.
|
|
275
|
+
|
|
276
|
+
For exposed credentials, follow the [channel token rules](https://developers.line.biz/en/docs/basics/channel-access-token/) for that token type: revoke a revocable token and replace it, or reissue a long-lived token and end any old-token grace period. Stateless tokens cannot be revoked and expire after their short validity period. Do not rely on removing a destination to revoke a token. Recheck receipt after replacement; cancellation cannot recall an accepted push. Recipient IDs are private identifiers, not authentication credentials; do not publish them with example settings.
|
|
277
|
+
|
|
278
|
+
## Teams setup and revocation
|
|
279
|
+
|
|
280
|
+
1. Open Workflows in Teams or Power Automate and create a flow with **When a Teams webhook request is received**. Choose **Anyone** authentication, not a tenant/user-authenticated mode. Configure the downstream Teams action and its target chat/channel for the fixed Adaptive Card. See [Workflows webhook setup](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook); use its Workflows instructions, not legacy Office connector instructions.
|
|
281
|
+
2. Confirm Workflows is available under the account, tenant policy, and applicable licensing. The workflow owner's connection and chat/channel posting privileges must permit the downstream action. Add appropriate co-owners and maintain its connections so an owner leaving does not leave an unmanaged flow. The extension cannot grant channel access, repair credentials, or change tenant policy.
|
|
282
|
+
3. Save the workflow and copy its current generated URL from the trigger. Use the [trigger URL migration guidance](https://learn.microsoft.com/en-us/power-automate/triggers-troubleshoot) if a URL changed; do not use an obsolete `logic.azure.com` URL or convert it by hand. Compare it with the [supported local URL policy](#microsoft-teams).
|
|
283
|
+
4. Run `/notify`, add a Microsoft Teams destination, and paste the complete URL into the masked input. Review the label and choose Save only or Save and use. Replacing the URL uses an empty masked input; the stored value is not displayed. Unsaved cancellation keeps the saved destination unchanged.
|
|
284
|
+
5. Use Send test, review the metadata, and confirm one external request. HTTP 202 reports trigger acceptance only. Check workflow run history, downstream action success, and the target chat/channel for the card. A local accepted result does not verify routing, account permissions, or receipt. The current integration remains unverified live; this is a user verification procedure, not a completed smoke result.
|
|
285
|
+
|
|
286
|
+
Anyone authentication makes URL secrecy essential. If it is exposed, disable the owning workflow to stop use, then revoke/replace the endpoint through the workflow's available controls or delete and recreate the workflow. Ensure the old endpoint is no longer usable before relying on a replacement; ask a workflow owner or administrator if needed. Copy the new generated URL into User settings and confirm its downstream result with Send test. Removing a destination or changing its label does not revoke the old URL. A cancelled HTTP request cannot recall an accepted trigger or Teams post.
|
|
287
|
+
|
|
25
288
|
## Persistence and recovery
|
|
26
289
|
|
|
27
290
|
Settings operations are ordered within the process, including across store instances for the same user path. Reads wait for pending writes. This is not a cross-process lock: simultaneous menu edits in different Pi processes can conflict.
|
|
28
291
|
|
|
29
|
-
Writes read the latest valid document, preserve unrelated fields and destination fields, and publish using a same-directory temporary file plus rename. Unknown provider data is retained during unrelated edits. Malformed JSON blocks writes instead of being overwritten with defaults. An existing non-object `destinations` value blocks destination changes. A non-object destination entry cannot be replaced with a new object. Repair these stored structures first; destination setup does not coerce them to empty defaults. A failed save keeps the previous file and effective state; the menu restores the previous displayed setting. A failed operation does not poison subsequent operations. Reload and shutdown await queued settings operations.
|
|
292
|
+
Writes read the latest valid document, preserve unrelated fields and destination fields, and publish using a same-directory temporary file plus rename. User settings writes use private `0600` permissions on POSIX, including replacement files. Unknown provider data is retained during unrelated edits. Malformed JSON blocks writes instead of being overwritten with defaults. An existing non-object `destinations` value blocks destination changes. A non-object destination entry cannot be replaced with a new object. Repair these stored structures first; destination setup does not coerce them to empty defaults. A failed save keeps the previous file and effective state; the menu restores the previous displayed setting. A failed operation does not poison subsequent operations. Reload and shutdown await queued settings operations.
|
|
293
|
+
|
|
294
|
+
If a file is malformed, repair it manually before saving. Disable notifications in every effective scope to stop new attempts and cancel pending reminders. Unloading the extension aborts owned delivery work, but cannot recall accepted messages. Revoke exposed tokens or Slack webhooks before replacing them in User settings.
|
|
295
|
+
|
|
296
|
+
### Reverting to a version without Teams
|
|
297
|
+
|
|
298
|
+
While the Teams-capable version is installed, remove Teams IDs from explicit Project selections in every affected project, then remove them from User selections and delete every saved Teams destination, including unselected ones. Confirm all remaining destinations and effective selections are supported before installing the older version and reloading. Unsupported saved destinations disable older routing even when unselected. Existing providers need no migration. Revoke exposed or unused workflow URLs separately through the owning workflow; removing settings does not revoke them.
|
|
299
|
+
|
|
300
|
+
### Reverting to a version without LINE
|
|
30
301
|
|
|
31
|
-
|
|
302
|
+
While this version is installed, remove LINE destination IDs from explicit Project selections in every affected project, then remove them from User selections and delete all saved LINE destinations, including unselected ones. Preserve the other supported providers and unrelated fields. Confirm the older version supports every saved destination and selected ID before installing it and reloading. Removing selections alone is insufficient: an unsupported unselected destination also disables older routing. Revoke unused or exposed channel tokens separately through LINE.
|
|
303
|
+
|
|
304
|
+
### Reverting to a version without the new providers
|
|
305
|
+
|
|
306
|
+
1. While the new build is still installed, remove the IDs of destinations whose provider is `ntfy`, `pushover`, `discord`, `bark`, or `webhook` from explicit Project selections in every affected project. Clear those overrides or select destinations the older version supports; Project arrays replace User selections.
|
|
307
|
+
2. Remove those IDs from User selections and remove every saved destination with one of these five provider IDs, including unselected destinations. Removal clears User selection atomically, but the current trusted Project must not explicitly select the destination.
|
|
308
|
+
3. Preserve existing Telegram, Gotify, Slack, and unknown fields. Confirm all saved destinations and effective selections are supported by the older version, then install it and reload.
|
|
309
|
+
|
|
310
|
+
Selections alone are insufficient: unsupported saved destinations disable routing even when unselected. No migration is needed for existing destinations. Revoke discarded credentials at each service separately; removing JSON does not revoke them. If the older version also lacks Slack, follow the Slack steps below.
|
|
311
|
+
|
|
312
|
+
### Reverting to a version without Slack
|
|
313
|
+
|
|
314
|
+
1. While the Slack-capable version is installed, remove Slack IDs from explicit Project selections in every affected project. Clear those overrides or select supported Telegram/Gotify IDs. Project arrays replace User selections.
|
|
315
|
+
2. Remove Slack IDs from User selections and remove the Slack destinations. Removing a destination also clears its User selection, but is blocked while the current trusted Project explicitly selects it.
|
|
316
|
+
3. Confirm that effective selections contain only supported destinations, then install the older version and reload.
|
|
317
|
+
|
|
318
|
+
Removing selections alone is not enough: older versions disable automatic delivery for any unsupported destination, even an unselected one. There is no migration for existing Telegram or Gotify destinations. Revoke webhooks in Slack separately if they are no longer needed.
|
|
32
319
|
|
|
33
320
|
## Inactivity timing
|
|
34
321
|
|
|
@@ -48,9 +335,17 @@ The coordinator observes `before_agent_start`, with `agent_start` as a fallback,
|
|
|
48
335
|
|
|
49
336
|
Metadata is collected at settlement through bounded Git subprocesses. Missing Git information is omitted. Pending metadata work is cancelled with its reminder. Once a delivery attempt starts, new user work does not cancel it; session replacement, reload, shutdown, or explicit test cancellation does. Late results cannot replace newer per-destination status. Test delivery bypasses automatic enablement and inactivity, requires explicit confirmation, and never changes automatic arming or history.
|
|
50
337
|
|
|
51
|
-
The provider contract validates destinations and sends a provider-neutral notification with a cancellation signal. Providers do not read sessions, change settings, schedule timers, or decide notification policy. The built-in provider map contains
|
|
338
|
+
The provider contract validates destinations and sends a provider-neutral notification with a cancellation signal. Providers do not read sessions, change settings, schedule timers, or decide notification policy. The built-in provider map contains Telegram, Gotify, Slack, ntfy, Pushover, Discord, Bark, Generic webhook, LINE, and Microsoft Teams. Transport results distinguish accepted, failed with a safe code, and cancelled; retry-after is diagnostic, not an automatic retry instruction.
|
|
339
|
+
|
|
340
|
+
All transports reject redirects, use a 10-second deadline covering the request and response read, make one attempt, and cap success response reads at 65,536 bytes. Errors expose only fixed codes, never tokens, request URLs, response bodies, or raw transport exceptions. ntfy, Pushover, Discord, Bark, Generic webhook, LINE, and Teams report HTTP 429 as `rate-limit`, with a positive integer `Retry-After` in seconds when available; fractional Discord retry values are not displayed. Retry-after is diagnostic only. Service acceptance does not prove device receipt, downstream delivery, or reading. Text clipping preserves Unicode code points; the [provider limits](#new-provider-fields) specify each byte or UTF-16 budget.
|
|
341
|
+
|
|
342
|
+
Telegram requests use its fixed HTTPS origin and do not enable paid broadcasts. Text is clipped to at most 4096 UTF-16 code units without splitting a Unicode code point. Telegram's JSON `ok` field and HTTP status are both checked.
|
|
343
|
+
|
|
344
|
+
Gotify posts JSON to `<serverUrl>/message` with `X-Gotify-Key` application-token authentication. The title and body are separate fields; emphasis metadata is not sent, and Markdown extras are not enabled. An unset priority is omitted so the server uses the application's default. A successful HTTP response must contain a message with positive integer `id` and `appid`, string `message`, and valid `date`. HTTP failures use a safe `http` code; HTTP 429 uses `rate-limit` and includes a positive integer `Retry-After` value when available. Server response text is never displayed.
|
|
345
|
+
|
|
346
|
+
Slack posts JSON to the validated webhook URL. It sends only the same provider-neutral title and metadata body as the other providers: hostname, session name/ID, working directory, available Git repository/worktree/branch, elapsed time, and settlement timestamp. Paths can disclose private information even when the home prefix is shortened. The selected channel's members can read this metadata. Prompts, assistant answers, code, tool output, Git remotes, credentials, and raw errors are not included.
|
|
52
347
|
|
|
53
|
-
|
|
348
|
+
Slack combines the title and body into one section block with a `plain_text` text object and `emoji: false`, not dynamic `mrkdwn`. Slack control characters `&`, `<`, and `>` are entity-escaped once so existing entity-like metadata also displays literally. The encoded text is capped at 3000 UTF-16 code units without splitting Unicode code points or entities; longer messages end with an ellipsis. Dynamic terminal controls are removed and metadata remains literal; mention and link expansion are disabled. The top-level fallback is the fixed text `Pi notification. Open Pi to review.` with markup and unfurling disabled. Screen readers and notification surfaces that use this fallback receive a generic reminder. Slack desktop notifications can extract block text instead, so metadata can still appear outside the channel view. Only HTTP 200 with the documented plain-text `ok` response counts as accepted; malformed or oversized success responses fail safely. HTTP 429 reports `rate-limit` with a valid positive integer `Retry-After` when available, without retrying. Other HTTP failures and invalid responses use fixed safe codes; response bodies and transport exceptions are never shown. Slack generally permits one webhook message per second, with short bursts; multiple destinations or rapid work periods can exceed workspace/channel limits. There is no automatic retry, queue, cooldown, or replay after reload. Accepted does not mean read.
|
|
54
349
|
|
|
55
350
|
## Authoritative references
|
|
56
351
|
|
|
@@ -59,6 +354,25 @@ Requests use Telegram's fixed HTTPS origin, reject redirects, and do not enable
|
|
|
59
354
|
- [Telegram getUpdates](https://core.telegram.org/bots/api#getupdates): manual chat-ID discovery; incompatible with active webhooks.
|
|
60
355
|
- [Telegram ResponseParameters](https://core.telegram.org/bots/api#responseparameters): `retry_after` on flood control.
|
|
61
356
|
- [Telegram rate limits](https://core.telegram.org/bots/faq#my-bot-is-hitting-limits-how-do-i-avoid-this): avoid more than one message per second in a chat, 20 per minute in a group, and about 30 per second across free broadcasts.
|
|
357
|
+
- [Gotify push messages](https://gotify.net/docs/pushmsg): application setup and application-token authentication.
|
|
358
|
+
- [Gotify API](https://gotify.net/api-docs) and [server API specification](https://raw.githubusercontent.com/gotify/server/v3.1.1/docs/spec.json): `POST /message`, message fields, and response schema.
|
|
359
|
+
- [Slack Incoming Webhooks](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks/): setup, commercial URL shape, fixed channel, secret handling, HTTP 200 `ok`, and failure conditions.
|
|
360
|
+
- [Slack text objects](https://docs.slack.dev/reference/block-kit/composition-objects/text-object/) and [section blocks](https://docs.slack.dev/reference/block-kit/blocks/section-block/): `plain_text` and the 3000-character text limit.
|
|
361
|
+
- [Slack message formatting](https://docs.slack.dev/messaging/formatting-message-text/#escaping): escaping control characters and disabling markup with `plain_text` and `mrkdwn: false`; desktop notifications can extract block text, while mobile notifications use top-level text.
|
|
362
|
+
- [Slack message posting](https://docs.slack.dev/reference/methods/chat.postMessage/): notification/screen-reader fallback text, parsing, link unfurling, and text limits; Incoming Webhooks follow Slack's messaging format.
|
|
363
|
+
- [Slack rate limits](https://docs.slack.dev/apis/web-api/rate-limits/): Incoming Webhooks, HTTP 429, and `Retry-After` seconds.
|
|
364
|
+
- [ntfy publishing](https://docs.ntfy.sh/publish/): JSON publishing, topic names, priority, and size limits; [access control](https://docs.ntfy.sh/config/#access-control): authentication, topic permissions, and access tokens.
|
|
365
|
+
- [Pushover Messages API](https://pushover.net/api): fixed endpoint, application/user credentials, normal priority, message limits, and numeric status responses.
|
|
366
|
+
- [Discord Execute Webhook](https://discord.com/developers/docs/resources/webhook#execute-webhook): endpoint, `wait=true`, content limits, Message response, and flags; [allowed mentions](https://discord.com/developers/docs/resources/message#allowed-mentions-object): explicit empty mention parsing.
|
|
367
|
+
- [Bark tutorial](https://bark.day.app/#/tutorial) and official server source at commit `640deaa151ddf79193202927b35ca2f14f65ee1d`: [JSON API](https://github.com/Finb/bark-server/blob/640deaa151ddf79193202927b35ca2f14f65ee1d/docs/API_V2.md), [push handler](https://github.com/Finb/bark-server/blob/640deaa151ddf79193202927b35ca2f14f65ee1d/route_push.go), [router](https://github.com/Finb/bark-server/blob/640deaa151ddf79193202927b35ca2f14f65ee1d/router.go), and [Basic authentication](https://github.com/Finb/bark-server/blob/640deaa151ddf79193202927b35ca2f14f65ee1d/route_auth.go). These establish `/push`, `device_key`, numeric acceptance, body logging, and the unsupported native Basic-auth mode.
|
|
368
|
+
- [Apple APNs payloads](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification): the 4096-byte regular notification payload limit; Bark's smaller local text budgets leave envelope space.
|
|
369
|
+
- [LINE push messages](https://developers.line.biz/en/reference/messaging-api/#send-push-message) and [text character count](https://developers.line.biz/en/docs/messaging-api/text-character-count/): fixed endpoint, eligibility, UTF-16 budget, and response conditions.
|
|
370
|
+
- [LINE OpenAPI](https://github.com/line/line-openapi/blob/main/messaging-api.yml) and [official SDK push tests](https://github.com/line/line-bot-sdk-nodejs/blob/master/test/line-bot-client.spec.ts): current `sentMessages` and legacy empty-object acceptance.
|
|
371
|
+
- [LINE channel access tokens](https://developers.line.biz/en/docs/basics/channel-access-token/), [user IDs](https://developers.line.biz/en/docs/messaging-api/getting-user-ids/), [group chats](https://developers.line.biz/en/docs/messaging-api/group-chats/), and [pricing](https://developers.line.biz/en/docs/messaging-api/pricing/): setup, revocation, recipient acquisition, and account-dependent message allowance.
|
|
372
|
+
- [Teams connector: Microsoft Teams Webhook](https://learn.microsoft.com/en-us/connectors/teams/#microsoft-teams-webhook): trigger authentication and card envelope; Anyone requests omit Authorization. This does not establish a complete URL or HTTP response contract.
|
|
373
|
+
- [Teams Workflows webhook setup](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook) and [trigger troubleshooting/URL migration](https://learn.microsoft.com/en-us/power-automate/triggers-troubleshoot): workflow creation, ownership, and current generated URLs. Published examples inform the supported client policy; they are not a normative universal URL grammar.
|
|
374
|
+
- [Adaptive Cards TextRun schema](https://learn.microsoft.com/en-us/adaptive-cards/schema-explorer/text-run) and [RichTextBlock schema](https://learn.microsoft.com/en-us/adaptive-cards/schema-explorer/rich-text-block): literal text without Markdown in TextRun.
|
|
375
|
+
- [RFC 9110: 202 Accepted](https://www.rfc-editor.org/rfc/rfc9110.html#name-202-accepted): acceptance is not completed processing; it does not establish which status every Teams workflow returns.
|
|
62
376
|
- [Pi extension lifecycle](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md#agent_start--agent_end--agent_before_settle--agent_settled).
|
|
63
377
|
|
|
64
378
|
Input classification follows the installed Pi `ProcessTerminal` and `StdinBuffer` sequence splitting, Pi's `parseKey`/`isKeyRelease`, and `TuiAltScreen` SGR mouse handling. Pure classifier tests cover keyboard, Unicode, paste, focus, press/release, motion, wheel, legacy mouse, CSI/OSC/DCS/APC replies, and unknown input. These tests do not prove that an event reaches the extension. Installed-runtime tests also pass events through real regular/fullscreen Pi renderers and check listener order, viewport keys, and focused-overlay branches. Physical terminal and multiplexer behavior remains unverified.
|
package/package.json
CHANGED
|
@@ -1,13 +1,26 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@narumitw/pi-notify",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.4.0",
|
|
4
|
+
"description": "Multi-provider notifications when Pi settles, with optional inactivity reminders.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"keywords": [
|
|
8
8
|
"pi-package",
|
|
9
9
|
"pi-extension",
|
|
10
10
|
"telegram",
|
|
11
|
+
"gotify",
|
|
12
|
+
"slack",
|
|
13
|
+
"ntfy",
|
|
14
|
+
"pushover",
|
|
15
|
+
"discord",
|
|
16
|
+
"bark",
|
|
17
|
+
"line",
|
|
18
|
+
"line-messaging-api",
|
|
19
|
+
"microsoft-teams",
|
|
20
|
+
"teams-workflows",
|
|
21
|
+
"power-automate",
|
|
22
|
+
"webhook",
|
|
23
|
+
"incoming-webhook",
|
|
11
24
|
"notifications"
|
|
12
25
|
],
|
|
13
26
|
"files": [
|