Tea journaling on ATProto (alpha) forked from arabica.social/arabica
oolong docs api notifications.md
4.1 kB · 105 lines
Markdown
at main

Notifications API #

The notification list is backed by the SQLite feed index that the firehose consumer maintains (internal/firehose/notifications.go). The JSON endpoint is read-only: it never changes read state, so a client can poll the list for a badge without silently clearing it (HandleNotificationsJSON). Marking read is a separate call.

GET /api/notifications #

Authentication required. Query parameters:

Param Type Default Description
cursor string — Opaque page cursor: pass the previous response's next_cursor verbatim.
— — — Page size is fixed at 30 (notificationsPerPage). There is no limit parameter.

Response #

{
  "notifications": [
    {
      "id": "1731670000000000000",
      "type": "like",
      "actor_did": "did:plc:xyz",
      "subject_uri": "at://did:plc:abc123/social.oolong.alpha.brew/3kbrew",
      "created_at": "2026-11-16T12:00:00Z",
      "read": false,
      "actor_handle": "bob.test",
      "actor_display_name": "Bob",
      "actor_avatar": "https://cdn.bsky.app/...",
      "link": "/brews/did:plc:abc123/3kbrew",
      "action_text": "liked your tea brew"
    }
  ],
  "next_cursor": ""
}
Field Type Description
notifications array Newest first. Always [] when empty.
notifications[].id string Stable notification id (timestamp-based).
type string like, comment, or comment_reply.
actor_did string Who performed the action.
subject_uri string The record that was acted on.
created_at string RFC 3339 timestamp.
read bool Read flag at the time of the query.
actor_handle string Cached handle, or the actor DID when the profile is unknown.
actor_display_name string Empty when unset or unknown.
actor_avatar string Empty when unset or unknown.
link string Local direct link (/{collection_path}/{did}/{rkey}); empty when the subject collection has no route.
action_text string Display string: liked your …, commented on your …, replied to your comment.
next_cursor string Cursor for the next page; empty at the end.

The entity noun inside action_text comes from the app's entity routes, so a custom app label changes that text, not the field set. link uses the owner's DID, not their handle, so it keeps working when a handle changes.

A user with no notifications, or a deployment without a feed index, gets {"notifications": [], "next_cursor": ""} with status 200 — not an error.

Errors #

Status Code When
401 authentication_required No session.
500 internal_error The feed index query failed.

POST /api/notifications/read #

Marks all notifications read for the viewer. There is no per-notification variant, and no body is read.

{"read": true}

The answer is always this body; there is no redirect variant. Cross-site posts are rejected by CSRF protection (403 permission_denied).

Status Code When
401 authentication_required No session.
500 internal_error The write failed.

The unread count #

GET /api/session exposes unread_notifications; that is the badge number, and reading the notification list does not change it.

Page behavior #

/notifications is a Solid page that calls the two endpoints above. Accept: application/json on the page route returns the same list as GET /api/notifications (routing.SPAOrJSON). A GET never clears the badge; the page marks read with POST /api/notifications/read once the list is shown.

Coverage #

internal/handlers/notifications_json_test.go covers the auth requirement, the empty-list shape, read-only behaviour, store failure (500), mark-read JSON with and without a JSON Accept header, and mark-read auth/store failures. The E2E fixture has no feed index, so it only exercises the empty-list path.