DNA: started from how-notifications-are-delivered.md
Root ·
Started from docs/dna/how-notifications-are-delivered.md in the Knowen repository: How Knowen works is kept with the code.
Changes to the content
# How notifications are delivered ⏎ **One event, many recipients.** When a node is created, edited or deleted, a comment is posted on it or on one of its changes, or someone is assigned, a background job works out who should hear about it, and writes one notification for each, with its **reasons**: ⏎ | Reason | Who | |---|---| | mentioned | an @handle in the comment | | assigned | assignees of the node or of any node above it | | participant | people in the conversation: the node's or change's author, earlier commenters | | author | the node's creator | | subscribed | a subscription to the node, or to a node above it with its descendants | | project | collaborators on the private graph | | following | people who follow the actor | | own_api | the actor, when the write came through their API token | ⏎ Proposals add **review** (owners whose nodes it changes) and **proposal** (its writers). ⏎ **Attention or information.** A notification is an **action item** when it needs an answer: a mention, a reply in your conversation, an assignment and comments on what you are assigned to. The rest are informational. ⏎ **Rules.** - The actor never hears about their own browser actions. - Every recipient must still be able to read the node; losing access hides earlier items too. - A deleted node is reported once; its earlier items disappear. - Reading only moves an item out of focus; nothing is deleted. ⏎ **Agents.** Through the API, `GET /api/v1/me/notifications` (filter by `unread` or `reason`) lists the caller's notifications, and `PATCH` or `POST …/mark_read` marks them read; an agent using your token reads yours. For separate agent accounts (**In development**), the rules are ready: an agent is told only what is aimed at it (**mentioned**, **assigned**), and its owner gets a copy with the reason **your_agent**, naming the agent. ⏎ **Messages are separate.** A conversation keeps a read position per participant, so "unread" is computed, not stored per message. An unread message schedules one email check 15 minutes later; it is sent only if the message is still unread, the person chose email, and the conversation is not muted. ⏎ **Subscriptions through the API:** `GET /api/v1/notifications`, and `POST` or `DELETE /api/v1/nodes/:id/notification` with `subtree: true` for a node and its descendants. ⏎ # Parents ⏎ * Agents and the API * Notifications and following⏎
Feedback00
No feedback yet. Say whether this change improves the node.
Sign in to add a new comment.
