0.1.2 zulip api constraints

pm/zulip-bot-constraints.org

@@ -0,0 +1,41 @@
+#+title: Zulip Bot Constraints and Auth Model
+#+created: [2026-04-14 Tue 15:25]
+#+updated: [2026-04-14 Tue 15:25]
+
+* initial research and recommendation
+Use a Zulip bot user for the bridge.
+
+Why:
+- smaller permission surface than a human account
+- API access is explicit and automatable
+- easier to treat as infrastructure than as a person
+
+Zulip messages can be sent as stream messages with a fixed topic using the API.
+Inbound updates can be read through Zulip's real-time events API via an event queue.
+
+Relevant API shape:
+- send message: type = stream, to = channel, topic = fixed topic
+- receive events: register an event queue, then long-poll get-events
+
+Bot API key access is restricted to the bot owner and organization administrators.
+
+* minimal zulip constraints
+| area | constraint |
+|------+------------|
+| identity | use a bot user, not a normal user account |
+| auth | bot API key needed; owner/admin can access it |
+| outbound | stream message + fixed topic |
+| inbound | event queue + long-poll events API |
+| scope | one stream/topic pair for v0 |
+| formatting | plain text is enough for the bridge |
+
+* what this means for v0
+- the Zulip side is not a general client UI problem
+- it is a bot that reads events and sends stream messages
+- no need for fancy topic routing yet
+- one fixed topic is enough to keep the bridge simple
+
+* summary
+Bot user + event queue + fixed stream/topic is the clean v0 path.
+
+It keeps Zulip acting like a relay endpoint, not a second full chat client.