openclaw-channel-zulip 2026.2.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.
- package/LICENSE +21 -0
- package/README.md +198 -0
- package/index.ts +17 -0
- package/openclaw.plugin.json +43 -0
- package/package.json +47 -0
- package/src/actions.ts +857 -0
- package/src/channel.test.ts +111 -0
- package/src/channel.ts +367 -0
- package/src/config-schema.ts +70 -0
- package/src/group-mentions.ts +13 -0
- package/src/normalize.ts +45 -0
- package/src/onboarding-helpers.ts +44 -0
- package/src/onboarding.ts +219 -0
- package/src/runtime.ts +14 -0
- package/src/types.ts +74 -0
- package/src/zulip/accounts.ts +157 -0
- package/src/zulip/client.ts +927 -0
- package/src/zulip/index.ts +9 -0
- package/src/zulip/monitor-helpers.ts +197 -0
- package/src/zulip/monitor.ts +909 -0
- package/src/zulip/probe.ts +69 -0
- package/src/zulip/send.ts +251 -0
- package/src/zulip/uploads.ts +101 -0
- package/tsconfig.json +19 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 FtlC-ian
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
# openclaw-channel-zulip
|
|
2
|
+
|
|
3
|
+
> Zulip channel plugin for [OpenClaw](https://github.com/openclaw/openclaw) — concurrent message processing, reaction indicators, file uploads, and full actions API.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/openclaw-channel-zulip)
|
|
6
|
+
[](https://opensource.org/licenses/MIT)
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Features
|
|
11
|
+
|
|
12
|
+
- ✅ **Concurrent message processing** — events fire-and-forget with staggered start times (200 ms apart), so a burst of incoming messages is handled in parallel rather than queued sequentially
|
|
13
|
+
- ✅ **Reaction indicators** — configurable emoji reactions signal processing state (`:working_on_it:` on start, ✅ on success, ❌ on error, with optional clear-on-finish)
|
|
14
|
+
- ✅ **File uploads** — inbound Zulip file attachments are downloaded and forwarded to the AI pipeline; outbound media is uploaded via Zulip's file upload API
|
|
15
|
+
- ✅ **Full actions API** — react, edit, delete, archive, move messages/topics; subscribe/unsubscribe streams; user management (requires `enableAdminActions: true`)
|
|
16
|
+
- ✅ **Topic directives** — reply topics can be scoped per-message, enabling organized thread-based conversations
|
|
17
|
+
- ✅ **Multi-account support** — run multiple Zulip bot accounts in one OpenClaw instance via the `accounts` map
|
|
18
|
+
- ✅ **DM & channel policies** — open / pairing / allowlist / disabled per account
|
|
19
|
+
- ✅ **Block streaming** — real-time streaming replies with configurable coalescing (min chars / idle timeout)
|
|
20
|
+
- ✅ **Onboarding wizard** — `openclaw onboard` walks you through setup interactively
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Installation
|
|
25
|
+
|
|
26
|
+
### Via plugin manager (recommended)
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
openclaw plugins install openclaw-channel-zulip
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
### Manual (for development or customization)
|
|
33
|
+
|
|
34
|
+
```sh
|
|
35
|
+
# 1. Clone the repo
|
|
36
|
+
git clone https://github.com/FtlC-ian/openclaw-channel-zulip.git
|
|
37
|
+
cd openclaw-channel-zulip
|
|
38
|
+
|
|
39
|
+
# 2. Install dependencies
|
|
40
|
+
npm install
|
|
41
|
+
|
|
42
|
+
# 3. Install as a local linked plugin
|
|
43
|
+
openclaw plugins install -l .
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## Configuration
|
|
49
|
+
|
|
50
|
+
### Enable the plugin
|
|
51
|
+
|
|
52
|
+
Add the plugin id to `plugins.allow` in `~/.openclaw/openclaw.json`:
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"plugins": {
|
|
57
|
+
"enabled": true,
|
|
58
|
+
"allow": ["zulip"]
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### Minimal configuration
|
|
64
|
+
|
|
65
|
+
```json
|
|
66
|
+
{
|
|
67
|
+
"channels": {
|
|
68
|
+
"zulip": {
|
|
69
|
+
"enabled": true,
|
|
70
|
+
"url": "https://your-org.zulipchat.com",
|
|
71
|
+
"email": "yourbot@your-org.zulipchat.com",
|
|
72
|
+
"apiKey": "your-zulip-api-key",
|
|
73
|
+
"streams": ["general", "support"],
|
|
74
|
+
"dmPolicy": "open",
|
|
75
|
+
"allowFrom": ["*"]
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### Full configuration reference
|
|
82
|
+
|
|
83
|
+
```json
|
|
84
|
+
{
|
|
85
|
+
"channels": {
|
|
86
|
+
"zulip": {
|
|
87
|
+
"enabled": true,
|
|
88
|
+
|
|
89
|
+
// Zulip server connection
|
|
90
|
+
"url": "https://your-org.zulipchat.com",
|
|
91
|
+
"email": "yourbot@your-org.zulipchat.com",
|
|
92
|
+
"apiKey": "your-zulip-api-key",
|
|
93
|
+
|
|
94
|
+
// Which streams to monitor ("*" = all)
|
|
95
|
+
"streams": ["general", "bot-testing"],
|
|
96
|
+
|
|
97
|
+
// Default topic for outbound messages with no explicit topic
|
|
98
|
+
"defaultTopic": "bot replies",
|
|
99
|
+
|
|
100
|
+
// Chat mode: "oncall" (mentioned only) | "onmessage" | "onchar"
|
|
101
|
+
"chatmode": "oncall",
|
|
102
|
+
|
|
103
|
+
// DM policy: "open" | "pairing" | "allowlist" | "disabled"
|
|
104
|
+
"dmPolicy": "open",
|
|
105
|
+
"allowFrom": ["*"],
|
|
106
|
+
|
|
107
|
+
// Group policy: "open" | "allowlist" | "disabled"
|
|
108
|
+
"groupPolicy": "open",
|
|
109
|
+
|
|
110
|
+
// Reaction indicators (shown while the bot is processing)
|
|
111
|
+
"reactions": {
|
|
112
|
+
"enabled": true,
|
|
113
|
+
"onStart": "working_on_it",
|
|
114
|
+
"onSuccess": "check",
|
|
115
|
+
"onError": "x",
|
|
116
|
+
"clearOnFinish": false
|
|
117
|
+
},
|
|
118
|
+
|
|
119
|
+
// Block streaming (real-time reply chunks)
|
|
120
|
+
"blockStreaming": true,
|
|
121
|
+
"blockStreamingCoalesce": {
|
|
122
|
+
"minChars": 1500,
|
|
123
|
+
"idleMs": 1000
|
|
124
|
+
},
|
|
125
|
+
|
|
126
|
+
// Enable admin-level actions (move/archive streams, manage users)
|
|
127
|
+
"enableAdminActions": false,
|
|
128
|
+
|
|
129
|
+
// Multi-account: uncomment to run multiple bots
|
|
130
|
+
// "accounts": {
|
|
131
|
+
// "primary": { "url": "...", "email": "...", "apiKey": "..." },
|
|
132
|
+
// "secondary": { "url": "...", "email": "...", "apiKey": "..." }
|
|
133
|
+
// }
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Then restart the Gateway:
|
|
140
|
+
|
|
141
|
+
```sh
|
|
142
|
+
openclaw gateway restart
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## How to get a Zulip API key
|
|
148
|
+
|
|
149
|
+
1. Log in to your Zulip organization
|
|
150
|
+
2. Go to **Settings → Your bots** (or create a bot at **Settings → Bots → Add a new bot**)
|
|
151
|
+
3. Copy the bot's **email** and **API key**
|
|
152
|
+
4. Use `https://your-org.zulipchat.com` as the `url`
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## Why concurrent processing?
|
|
157
|
+
|
|
158
|
+
Most channel plugin implementations process incoming messages one at a time — each message waits for the previous one to finish before starting. Under load (e.g. a burst of messages after reconnect) this creates noticeable latency for later messages.
|
|
159
|
+
|
|
160
|
+
This plugin processes events **concurrently**: each message is dispatched immediately (fire-and-forget with error handling) and a small 200 ms stagger is introduced between starts for natural pacing. The result is that ten simultaneous messages all start processing within ~2 seconds of each other instead of serially.
|
|
161
|
+
|
|
162
|
+
---
|
|
163
|
+
|
|
164
|
+
## Updating
|
|
165
|
+
|
|
166
|
+
If installed via npm:
|
|
167
|
+
|
|
168
|
+
```sh
|
|
169
|
+
openclaw plugins update zulip
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
If installed from local source:
|
|
173
|
+
|
|
174
|
+
```sh
|
|
175
|
+
cd openclaw-channel-zulip
|
|
176
|
+
git pull
|
|
177
|
+
openclaw gateway restart
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## Plugin ID
|
|
183
|
+
|
|
184
|
+
The plugin id is `zulip` (defined in `openclaw.plugin.json`). Use this id in `plugins.allow` and with `openclaw plugins` commands.
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
## Resources
|
|
189
|
+
|
|
190
|
+
- [OpenClaw plugin documentation](https://openclaw.dev/plugins)
|
|
191
|
+
- [Zulip Bot API docs](https://zulip.com/api/overview)
|
|
192
|
+
- [OpenClaw channel plugin reference](https://openclaw.dev/channels/zulip)
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## License
|
|
197
|
+
|
|
198
|
+
MIT © FtlC-ian
|
package/index.ts
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
|
|
2
|
+
import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
|
|
3
|
+
import { zulipPlugin } from "./src/channel.js";
|
|
4
|
+
import { setZulipRuntime } from "./src/runtime.js";
|
|
5
|
+
|
|
6
|
+
const plugin = {
|
|
7
|
+
id: "zulip",
|
|
8
|
+
name: "Zulip",
|
|
9
|
+
description: "Zulip channel plugin",
|
|
10
|
+
configSchema: emptyPluginConfigSchema(),
|
|
11
|
+
register(api: OpenClawPluginApi) {
|
|
12
|
+
setZulipRuntime(api.runtime);
|
|
13
|
+
api.registerChannel({ plugin: zulipPlugin });
|
|
14
|
+
},
|
|
15
|
+
};
|
|
16
|
+
|
|
17
|
+
export default plugin;
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "zulip",
|
|
3
|
+
"channels": ["zulip"],
|
|
4
|
+
"configSchema": {
|
|
5
|
+
"type": "object",
|
|
6
|
+
"additionalProperties": false,
|
|
7
|
+
"properties": {}
|
|
8
|
+
},
|
|
9
|
+
"uiHints": {
|
|
10
|
+
"url": {
|
|
11
|
+
"label": "Zulip Server URL",
|
|
12
|
+
"placeholder": "https://your-org.zulipchat.com"
|
|
13
|
+
},
|
|
14
|
+
"email": {
|
|
15
|
+
"label": "Bot Email",
|
|
16
|
+
"placeholder": "bot@your-org.zulipchat.com"
|
|
17
|
+
},
|
|
18
|
+
"apiKey": {
|
|
19
|
+
"label": "API Key",
|
|
20
|
+
"sensitive": true
|
|
21
|
+
},
|
|
22
|
+
"streams": {
|
|
23
|
+
"label": "Streams to Monitor",
|
|
24
|
+
"placeholder": "[\"general\", \"random\"]"
|
|
25
|
+
},
|
|
26
|
+
"defaultTopic": {
|
|
27
|
+
"label": "Default Topic",
|
|
28
|
+
"placeholder": "general chat"
|
|
29
|
+
},
|
|
30
|
+
"dmPolicy": {
|
|
31
|
+
"label": "DM Policy"
|
|
32
|
+
},
|
|
33
|
+
"groupPolicy": {
|
|
34
|
+
"label": "Group Policy"
|
|
35
|
+
},
|
|
36
|
+
"requireMention": {
|
|
37
|
+
"label": "Require @mention in Streams"
|
|
38
|
+
},
|
|
39
|
+
"reactions.enabled": {
|
|
40
|
+
"label": "Reaction Indicators"
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "openclaw-channel-zulip",
|
|
3
|
+
"version": "2026.2.4",
|
|
4
|
+
"description": "Zulip channel plugin for OpenClaw — concurrent message processing, reaction indicators, file uploads, and full actions API",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"author": "FtlC-ian",
|
|
7
|
+
"license": "MIT",
|
|
8
|
+
"keywords": [
|
|
9
|
+
"openclaw",
|
|
10
|
+
"openclaw-plugin",
|
|
11
|
+
"openclaw-channel",
|
|
12
|
+
"zulip",
|
|
13
|
+
"chatbot",
|
|
14
|
+
"bot"
|
|
15
|
+
],
|
|
16
|
+
"repository": {
|
|
17
|
+
"type": "git",
|
|
18
|
+
"url": "https://github.com/FtlC-ian/openclaw-channel-zulip.git"
|
|
19
|
+
},
|
|
20
|
+
"homepage": "https://github.com/FtlC-ian/openclaw-channel-zulip#readme",
|
|
21
|
+
"bugs": {
|
|
22
|
+
"url": "https://github.com/FtlC-ian/openclaw-channel-zulip/issues"
|
|
23
|
+
},
|
|
24
|
+
"dependencies": {
|
|
25
|
+
"zod": "^4.3.6"
|
|
26
|
+
},
|
|
27
|
+
"devDependencies": {
|
|
28
|
+
"openclaw": "*"
|
|
29
|
+
},
|
|
30
|
+
"openclaw": {
|
|
31
|
+
"extensions": [
|
|
32
|
+
"./index.ts"
|
|
33
|
+
],
|
|
34
|
+
"channel": {
|
|
35
|
+
"id": "zulip",
|
|
36
|
+
"label": "Zulip",
|
|
37
|
+
"selectionLabel": "Zulip (plugin)",
|
|
38
|
+
"docsLabel": "zulip",
|
|
39
|
+
"blurb": "Zulip streams/topics with reaction-based reply indicators (plugin, installed separately).",
|
|
40
|
+
"order": 70
|
|
41
|
+
},
|
|
42
|
+
"install": {
|
|
43
|
+
"npmSpec": "openclaw-channel-zulip",
|
|
44
|
+
"defaultChoice": "npm"
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
}
|