notefeed 0.5.0

Released 2026-10-01 · on GitHub

Feeds, read links and a REST API.

Breaking: this release replaces the single token-protected feed of 0.3. NOTEFEED_TOKEN, /api/notes and /feed.xml are gone, and the client packages change accordingly (see "Upgrading" in the client docs).

Feeds

• One instance, many feeds. A feed is identified by its name: post to POST /<feed>, read it at /<feed>. There are no accounts. The name is the write key, so pick one that's hard to guess (the start page suggests one).
• Read links. Every feed has a read-only link, /r/<read id>, plus RSS at /r/<read id>/feed.xml. They show the notes but never the feed's name, so they're safe to share or put in a feed reader.
• Optional instance password (NOTEFEED_PASSWORD): it locks posting and the web UI, while read links stay public. Wrong passwords are rate-limited, and after logging in you return to the page you came from.
• Limits for public instances:
  • posts are rate-limited per client (NOTEFEED_RATE_LIMIT, NOTEFEED_TRUST_PROXY behind a proxy)
  • NOTEFEED_MAX_FEEDS and NOTEFEED_MAX_NOTES_PER_FEED are optional caps
  • bodies are capped while they stream in

REST API

• Versioned and documented under /api/v1: post notes, list a feed's notes as JSON with paging (limit, before → next), get one note, and read by read id without a password. Errors are JSON with a stable code.
• Self-describing: each instance serves its OpenAPI description at /api/v1/openapi.json, and docs.notefeed.me renders it. It's generated from the server's code.
• curl -F markdown=@note.md works, and so does curl -d. HEAD works on every GET endpoint.

Client packages 0.5.0 (PyPI and npm notefeed)

• Generated from the API description, with a small Client on top: post, notes() (walks every page), note, the read-id variants, and from_env() / fromEnv(). Errors are classes mapped from the API's code, and a redirect or a non-API answer is an error, never a silent success.
• New command: notefeed notes [--limit N] [--json].
• Python now needs 3.11 or newer and depends on httpx. Node still has no dependencies.

Web UI

• A start page to open a feed, a page per feed, and read-only views.
• The compose box works without JavaScript and shows errors inline with it.

Under the hood

• The server code is a framework-free backend behind a single boundary module.
• Every POST is handled by one write path, routed by method and path.
• Architecture decisions are recorded in docs/adr (0001–0006).
• End-to-end tests run in a real browser against the production build.